Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
import { assertCompositableSurfaceRef } from "@hypit/media";
import type { CompositableSurfaceRef, FontArtifactRef } from "@hypit/media";
import { timelineFrameCount } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import { assertCompositionIdentity } from "@hypit/composition";
import type {
Composition,
Track,
VisualAnimation,
VisualAttribute,
VisualElement,
VisualPresent,
VisualSourceTimeRational,
VisualSourceTimePiece,
VisualStyleDeclaration,
VisualTrack,
} from "@hypit/composition";
import { canonicalStringify, isResourceId } from "@hypit/hypit/protocol";
import type { BlobRef, ResourceId } from "@hypit/hypit/protocol";
import { VISUAL_IR_V1 } from "@hypit/composition";
import { readHtmlVisual, htmlVisualHtml, htmlVisualScript } from "./html-visual.js";
import { presentationCaptureScopeRuntime } from "./capture-scope.js";
import { presentationVisibilityScript } from "./visibility.js";
import { frameSelectionRuntime, frameWorkIndexRuntime } from "./frame-work.js";
import type {
ResourceUrlResolver,
HtmlArtifact,
HtmlProgram,
HtmlFrameSpan,
HtmlFrameSource,
} from "./types.js";
import {
collectTerminalTextFonts,
renderGlyphPaintedString,
renderTerminalTextElement,
terminalTextLayoutScript,
} from "./text.js";
const NANOSECONDS = 1_000_000_000n;
const RESOURCE_URI = /hypit-resource:\/\/(res_[a-zA-Z0-9._:-]+)/gu;
const SURFACE_RESOURCE = /data-hypit-surface-resource="(res_[a-zA-Z0-9._:-]+)"/gu;
function escapeHtml(value: string): string {
return value
.replaceAll("&", "&")
.replaceAll("<", "<")
.replaceAll(">", ">")
.replaceAll('"', """)
.replaceAll("'", "'");
}
function frameSeconds(frame: number, numerator: number, denominator: number): string {
const nanos = BigInt(frame) * BigInt(denominator) * NANOSECONDS / BigInt(numerator);
const whole = nanos / NANOSECONDS;
const remainder = nanos % NANOSECONDS;
if (remainder === 0n) return String(whole);
return `${whole}.${String(remainder).padStart(9, "0").replace(/0+$/u, "")}`;
}
function fpsDecimal(numerator: number, denominator: number): string {
const scale = 1_000_000_000_000n;
const scaled = BigInt(numerator) * scale / BigInt(denominator);
const whole = scaled / scale;
const remainder = scaled % scale;
if (remainder === 0n) return String(whole);
return `${whole}.${String(remainder).padStart(12, "0").replace(/0+$/u, "")}`;
}
function fpsRational(numerator: number, denominator: number): string {
return denominator === 1 ? String(numerator) : `${numerator}/${denominator}`;
}
function rationalDecimal(numerator: bigint, denominator: bigint): string {
if (denominator <= 0n) throw new Error("HTML renderer rational denominator must be positive.");
const scale = 1_000_000_000_000n;
const scaled = numerator * scale / denominator;
const whole = scaled / scale;
const remainder = scaled % scale;
if (remainder === 0n) return String(whole);
return `${whole}.${String(remainder).padStart(12, "0").replace(/0+$/u, "")}`;
}
function sourceSeconds(frame: VisualSourceTimeRational, frameRate: VisualSourceTimeRational): string {
return rationalDecimal(
BigInt(frame.numerator) * BigInt(frameRate.denominator),
BigInt(frame.denominator) * BigInt(frameRate.numerator),
);
}
function sourcePosition(piece: VisualSourceTimePiece, offset: number): {
readonly position: VisualSourceTimeRational;
readonly cycle: bigint;
} {
const denominator = BigInt(piece.sourceAtStart.denominator) * BigInt(piece.rate.denominator);
const raw = BigInt(piece.sourceAtStart.numerator) * BigInt(piece.rate.denominator)
+ BigInt(offset) * BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
if (piece.wrap === undefined) {
if (raw < 0n || raw > BigInt(Number.MAX_SAFE_INTEGER) || denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
throw new Error("HTML renderer visual source time exceeds safe arithmetic.");
}
return { position: { numerator: Number(raw), denominator: Number(denominator) }, cycle: 0n };
}
const start = BigInt(piece.wrap.startFrame) * denominator;
const length = BigInt(piece.wrap.endFrameExclusive - piece.wrap.startFrame) * denominator;
const delta = raw - start;
const cycle = delta >= 0n ? delta / length : -((-delta + length - 1n) / length);
const wrapped = ((delta % length) + length) % length;
const numerator = start + wrapped;
if (numerator > BigInt(Number.MAX_SAFE_INTEGER) || denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
throw new Error("HTML renderer visual sampling exceeds safe arithmetic.");
}
return { position: { numerator: Number(numerator), denominator: Number(denominator) }, cycle };
}
function sourceTimeRuns(piece: VisualSourceTimePiece): Array<{
readonly startFrame: number;
readonly endFrameExclusive: number;
readonly sourceFrame: VisualSourceTimeRational;
}> {
const length = piece.target.endFrameExclusive - piece.target.startFrame;
const runs: Array<{ startFrame: number; endFrameExclusive: number; sourceFrame: VisualSourceTimeRational }> = [];
// Keep a hold as the interval it is. HTMLMediaElement cannot accept a zero
// playbackRate, but that browser limitation belongs to the render/preview
// adapters; expanding the shared sampling description here would turn one
// authored relation into O(target frames) DOM and Provider work.
if (piece.rate.numerator === 0 || piece.wrap === undefined) {
return [{
startFrame: piece.target.startFrame,
endFrameExclusive: piece.target.endFrameExclusive,
sourceFrame: sourcePosition(piece, 0).position,
}];
}
let runStart = 0;
while (runStart < length) {
const runSource = sourcePosition(piece, runStart);
let left = runStart + 1;
let right = length;
while (left < right) {
const middle = left + Math.floor((right - left) / 2);
const cycle = sourcePosition(piece, middle).cycle;
const crossed = piece.rate.numerator > 0 ? cycle > runSource.cycle : cycle < runSource.cycle;
if (crossed) right = middle;
else left = middle + 1;
}
runs.push({
startFrame: piece.target.startFrame + runStart,
endFrameExclusive: piece.target.startFrame + left,
sourceFrame: runSource.position,
});
runStart = left;
}
return runs;
}
function sampledPlaybackRate(
rate: VisualSourceTimeRational,
sourceFrameRate: VisualSourceTimeRational,
programNumerator: number,
programDenominator: number,
): string {
// The exact zero rate remains in data-hypit-source-rate for adapters that
// place discrete frames. This positive fallback is only the legal native
// HTMLMediaElement value; preview adapters pause and seek held elements.
if (rate.numerator <= 0) return "1";
return rationalDecimal(
BigInt(rate.numerator) * BigInt(programNumerator) * BigInt(sourceFrameRate.denominator),
BigInt(rate.denominator) * BigInt(programDenominator) * BigInt(sourceFrameRate.numerator),
);
}
function percentage(frame: number, totalFrames: number): string {
const scale = 1_000_000_000n;
const scaled = BigInt(frame) * 100n * scale / BigInt(totalFrames);
const whole = scaled / scale;
const remainder = scaled % scale;
if (remainder === 0n) return `${whole}%`;
return `${whole}.${String(remainder).padStart(9, "0").replace(/0+$/u, "")}%`;
}
export function htmlProgramResourceUri(resource: ResourceId): string {
if (!isResourceId(resource)) throw new Error("HTML renderer Resource id is invalid.");
return `hypit-resource://${resource}`;
}
/** Keep compiler-owned media inert until the page has applied its render selection. */
function deferredResource(attribute: "src" | "href", resource: ResourceId): string {
return `data-hypit-resource-${attribute}="${escapeHtml(htmlProgramResourceUri(resource))}"`;
}
function css(style: readonly VisualStyleDeclaration[]): string {
return style.map(({ name, value }) => `${name}:${String(value)}`).join(";");
}
function pixelDimension(style: readonly VisualStyleDeclaration[], name: string): number | undefined {
const value = style.find((declaration) => declaration.name === name)?.value;
if (typeof value !== "string") return undefined;
const match = /^(?:0|[1-9][0-9]*(?:\.[0-9]+)?)px$/u.exec(value);
if (match === null) return undefined;
const parsed = Number.parseFloat(value.slice(0, -2));
return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
}
function attributes(values: readonly VisualAttribute[] | undefined): string {
return (values ?? []).map(({ name, value }) => ` ${name}="${escapeHtml(value)}"`).join("");
}
type StableDomId = (parts: readonly string[]) => string;
/** Allocate short document-local names in first-use order; authored ids stay in data attributes. */
function createStableDomId(): StableDomId {
const ids = new Map<string, string>();
return (parts) => {
const key = canonicalStringify(parts);
const existing = ids.get(key);
if (existing !== undefined) return existing;
const id = `hypit-${ids.size + 1}`;
ids.set(key, id);
return id;
};
}
function exactFontFamily(font: FontArtifactRef, stableId: StableDomId): string {
return stableId(["font", canonicalStringify(font)]);
}
function exactFontStyle(element: VisualElement, stableId: StableDomId): string[] {
if (element.kind !== "text") return [];
const first = element.fonts[0]!;
return [
`font-family:${element.fonts.map((font) => exactFontFamily(font, stableId)).join(",")}`,
`font-weight:${first.weight}`,
`font-style:${first.style}`,
"font-synthesis:none",
];
}
type ElementContext = {
readonly trackId: string;
readonly presentId: string;
readonly presentStart: string;
readonly presentDuration: string;
readonly presentDurationFrames: number;
readonly presentStartFrame: number;
readonly programNumerator: number;
readonly programDenominator: number;
readonly stackIndex: number;
readonly emittedFilterIds: Set<string>;
readonly sharedGlyphFilterDefinitions: string[];
readonly stableId: StableDomId;
readonly frameSources: HtmlFrameSource[];
};
/** Every emitted element, including SVG mask sources, keeps the same authored frame clock. */
function elementPresentation(element: VisualElement, context: ElementContext) {
const id = context.stableId([context.trackId, context.presentId, element.id]);
const animationName = element.animation === undefined
? undefined
: context.stableId(["animation", context.trackId, context.presentId, element.id]);
const animationDurationFrames = element.animation === undefined
? context.presentDurationFrames
: Math.max(context.presentDurationFrames, element.animation.keyframes.at(-1)?.atFrame ?? 0);
const animationDuration = frameSeconds(animationDurationFrames, context.programNumerator, context.programDenominator);
const inlineStyle = [
css(element.style),
...exactFontStyle(element, context.stableId),
...(animationName === undefined ? [] : [
`animation-name:${animationName}`,
`animation-duration:${animationDuration}s`,
"animation-fill-mode:both",
// An independently launched render worker may begin at any frame. Keep
// CSS animations inert from first paint so HTML renderer' exact seek is
// the only clock; otherwise page-load time leaks into the first frame of
// each partition before the runtime pauses the animation.
"animation-play-state:paused",
"animation-timing-function:linear",
]),
].filter(Boolean).join(";");
const commonAttributes = `id="${id}" data-hypit-element-id="${escapeHtml(element.id)}"${attributes(element.attributes)}`;
const animationAttributes = animationName === undefined
? ""
: ` data-hypit-frame-animation data-hypit-animation-start-frame="${context.presentStartFrame}" data-hypit-animation-sample-frames="${context.presentDurationFrames}"`;
const common = `${commonAttributes}${animationAttributes} style="${escapeHtml(inlineStyle)}"`;
return { inlineStyle, commonAttributes: `${commonAttributes}${animationAttributes}`, common };
}
function renderElement(
element: VisualElement,
children: ReadonlyMap<string, readonly VisualElement[]>,
context: ElementContext,
): string {
const { inlineStyle, commonAttributes, common } = elementPresentation(element, context);
const id = context.stableId([context.trackId, context.presentId, element.id]);
if (element.kind === "mask") {
const direct = children.get(element.id) ?? [];
const maskRoot = direct.find((child) => child.id === element.maskElement);
const contentRoot = direct.find((child) => child.id === element.contentElement);
if (maskRoot === undefined || contentRoot === undefined || direct.length !== 2) {
throw new Error(`Local mask ${element.id} is missing its declared owned roots.`);
}
const maskId = context.stableId([context.trackId, context.presentId, element.id, "mask"]);
const maskWidth = pixelDimension(element.style, "width");
const maskHeight = pixelDimension(element.style, "height");
const viewport = maskWidth === undefined || maskHeight === undefined
? ""
: ` viewBox="0 0 ${maskWidth} ${maskHeight}" preserveAspectRatio="none"`;
const renderOwned = (child: VisualElement) => renderElement(child, children, context);
if ((children.get(maskRoot.id) ?? []).length !== 0) {
throw new Error(`Local mask ${element.id} mask source must be one terminal owned element.`);
}
const maskSource = (() => {
const sourcePresentation = elementPresentation(maskRoot, context);
if (maskRoot.kind === "text") {
const alignment = maskRoot.style.find((declaration) => declaration.name === "text-align")?.value;
const anchor = alignment === "right" || alignment === "end" ? "end" : alignment === "left" || alignment === "start" ? "start" : "middle";
const blockAlignment = maskRoot.style.find((declaration) => declaration.name === "align-items")?.value;
const paddingLeft = pixelDimension(maskRoot.style, "padding-left") ?? 0;
const paddingRight = pixelDimension(maskRoot.style, "padding-right") ?? 0;
const paddingTop = pixelDimension(maskRoot.style, "padding-top") ?? 0;
const paddingBottom = pixelDimension(maskRoot.style, "padding-bottom") ?? 0;
const x = maskWidth === undefined
? anchor === "start" ? "0" : anchor === "end" ? "100%" : "50%"
: String(anchor === "start" ? paddingLeft : anchor === "end" ? maskWidth - paddingRight : (paddingLeft + maskWidth - paddingRight) / 2);
const y = maskHeight === undefined
? blockAlignment === "flex-start" ? "0" : blockAlignment === "flex-end" ? "100%" : "50%"
: String(blockAlignment === "flex-start" ? paddingTop : blockAlignment === "flex-end" ? maskHeight - paddingBottom : (paddingTop + maskHeight - paddingBottom) / 2);
const baseline = blockAlignment === "flex-start" ? "text-before-edge" : blockAlignment === "flex-end" ? "text-after-edge" : "central";
const textStyle = `${sourcePresentation.inlineStyle};fill:currentColor`;
return `<text ${sourcePresentation.commonAttributes} x="${x}" y="${y}" text-anchor="${anchor}" dominant-baseline="${baseline}" style="${escapeHtml(textStyle)}">${escapeHtml(maskRoot.text)}</text>`;
}
if (maskRoot.kind === "text-flow" || maskRoot.kind === "path-text") {
return `<foreignObject x="0" y="0" width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="position:relative;width:100%;height:100%">${renderOwned(maskRoot)}</div></foreignObject>`;
}
if (maskRoot.kind === "image") {
return `<image ${sourcePresentation.common} x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" ${deferredResource("href", maskRoot.artifact.resource)}/>`;
}
if (maskRoot.kind === "surface" && maskRoot.surface.timing.kind === "still") {
return `<image ${sourcePresentation.common} data-hypit-surface-resource="${maskRoot.surface.artifact.resource}" x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" ${deferredResource("href", maskRoot.surface.artifact.resource)}/>`;
}
throw new Error(`Local mask ${element.id} requires a terminal owned text, image or still Surface mask source.`);
})();
return `<svg ${common}${viewport} width="100%" height="100%" overflow="visible"><defs><mask id="${maskId}" x="0" y="0" width="100%" height="100%" maskUnits="userSpaceOnUse" maskContentUnits="userSpaceOnUse" style="mask-type:${element.mode}">${maskSource}</mask></defs><foreignObject x="0" y="0" width="100%" height="100%" mask="url(#${maskId})"><div xmlns="http://www.w3.org/1999/xhtml" style="position:relative;width:100%;height:100%">${renderOwned(contentRoot)}</div></foreignObject></svg>`;
}
if (element.kind === "program") {
const program = readHtmlVisual(element.program);
const slots = new Map((children.get(element.id) ?? []).map(child => [child.id, renderElement(child, children, context)]));
return `<div ${common}>${htmlVisualHtml(program, slots)}</div>`;
}
const descendants = (children.get(element.id) ?? [])
.map((child) => renderElement(child, children, context))
.join("");
if (element.kind === "box") return `<div ${common}>${descendants}</div>`;
const textContext = {
trackId: context.trackId,
presentId: context.presentId,
durationFrames: context.presentDurationFrames,
durationSeconds: context.presentDuration,
presentStartFrame: context.presentStartFrame,
programNumerator: context.programNumerator,
programDenominator: context.programDenominator,
escape: escapeHtml,
stableId: context.stableId,
exactFontFamily: (font: FontArtifactRef) => exactFontFamily(font, context.stableId),
baseStyle: inlineStyle,
commonAttributes,
emittedFilterIds: context.emittedFilterIds,
sharedGlyphFilterDefinitions: context.sharedGlyphFilterDefinitions,
};
if (element.kind === "text") {
const body = element.paints === undefined
? escapeHtml(element.text)
: renderGlyphPaintedString(element.text, element.paints, textContext);
return `<div ${common}>${body}${descendants}</div>`;
}
if (element.kind === "text-flow" || element.kind === "path-text") {
return renderTerminalTextElement(element, textContext);
}
if ((element.kind === "video" || element.kind === "surface") && element.sourceTime !== undefined) {
const artifact = element.kind === "surface" ? element.surface.artifact : element.artifact;
let part = 0;
return element.sourceTime.pieces.flatMap((piece) => sourceTimeRuns(piece).map((run) => {
part += 1;
const startFrame = context.presentStartFrame + run.startFrame;
const durationFrames = run.endFrameExclusive - run.startFrame;
const partId = `${id}-sample-${String(part).padStart(4, "0")}`;
context.frameSources.push({
id: partId,
resource: artifact.resource,
startFrame,
endFrameExclusive: startFrame + durationFrames,
sourceFrame: { ...run.sourceFrame },
sourceRate: { ...piece.rate },
sourceFrameRate: { ...element.sourceTime!.sourceFrameRate },
});
const media = [
`id="${partId}"`,
`data-hypit-element-id="${escapeHtml(element.id)}"`,
`data-hypit-sampling-part="${part}"`,
`data-hypit-source-frame="${run.sourceFrame.numerator}/${run.sourceFrame.denominator}"`,
`data-hypit-source-rate="${piece.rate.numerator}/${piece.rate.denominator}"`,
`data-hypit-start-frame="${startFrame}"`,
`data-hypit-end-frame="${startFrame + durationFrames}"`,
`data-hypit-source-fps="${element.sourceTime!.sourceFrameRate.numerator}/${element.sourceTime!.sourceFrameRate.denominator}"`,
`style="${escapeHtml(inlineStyle)}"`,
attributes(element.attributes).trim(),
"muted",
"playsinline",
...(element.kind === "surface" ? [
`data-hypit-surface-resource="${element.surface.artifact.resource}"`,
`data-hypit-alpha-mode="${element.surface.alphaMode}"`,
`data-hypit-color-space="${element.surface.colorSpace}"`,
`width="${element.surface.width}"`,
`height="${element.surface.height}"`,
] : []),
].filter(Boolean).join(" ");
return `<video ${media} ${deferredResource("src", artifact.resource)}></video>`;
})).join("");
}
if (element.kind === "surface") {
const surface = [
`data-hypit-surface-resource="${element.surface.artifact.resource}"`,
`data-hypit-alpha-mode="${element.surface.alphaMode}"`,
`data-hypit-color-space="${element.surface.colorSpace}"`,
`width="${element.surface.width}"`,
`height="${element.surface.height}"`,
].join(" ");
if (element.surface.timing.kind === "still") return `<img ${common} ${surface} ${deferredResource("src", element.surface.artifact.resource)}/>`;
throw new Error(`Timed Surface ${element.id} has no source-time map.`);
}
const media = [
element.kind === "video" && element.muted !== false ? "muted" : "",
element.kind === "video" ? "playsinline" : "",
].filter(Boolean).join(" ");
if (element.kind === "image") return `<img ${common} ${media} ${deferredResource("src", element.artifact.resource)}/>`;
throw new Error(`Timed visual element ${element.id} has no source-time map.`);
}
function renderVisualPresent(
track: VisualTrack,
present: VisualPresent,
stackIndex: number,
numerator: number,
denominator: number,
emittedFilterIds: Set<string>,
sharedGlyphFilterDefinitions: string[],
stableId: StableDomId,
frameSources: HtmlFrameSource[],
): string {
const start = frameSeconds(present.span.startFrame, numerator, denominator);
const duration = frameSeconds(present.span.endFrameExclusive - present.span.startFrame, numerator, denominator);
const children = new Map<string, VisualElement[]>();
for (const element of present.elements) {
if (element.parent === undefined) continue;
const siblings = children.get(element.parent) ?? [];
siblings.push(element);
children.set(element.parent, siblings);
}
for (const siblings of children.values()) siblings.sort((left, right) => left.order - right.order || left.id.localeCompare(right.id));
const root = present.elements.find((element) => element.parent === undefined)!;
const contents = renderElement(root, children, {
trackId: track.id,
presentId: present.id,
presentStart: start,
presentDuration: duration,
presentDurationFrames: present.span.endFrameExclusive - present.span.startFrame,
presentStartFrame: present.span.startFrame,
programNumerator: numerator,
programDenominator: denominator,
stackIndex,
emittedFilterIds,
sharedGlyphFilterDefinitions,
stableId,
frameSources,
});
return `<div class="hypit-visual-present" data-hypit-track-id="${escapeHtml(track.id)}" data-hypit-present-id="${escapeHtml(present.id)}" data-hypit-present-start-frame="${present.span.startFrame}" data-hypit-present-end-frame="${present.span.endFrameExclusive}" data-hypit-present-order="${present.order}" data-hypit-z="${present.z}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${present.visibility === undefined ? contents : `<div data-hypit-visibility="${escapeHtml(JSON.stringify(present.visibility))}" style="position:absolute;inset:0">${contents}</div>`}</div>`;
}
function renderAnimationRules(track: VisualTrack, present: VisualPresent, stableId: StableDomId): string[] {
const presentDurationFrames = present.span.endFrameExclusive - present.span.startFrame;
return present.elements.flatMap((element) => {
if (element.animation === undefined) return [];
const durationFrames = Math.max(presentDurationFrames, element.animation.keyframes.at(-1)?.atFrame ?? 0);
const name = stableId(["animation", track.id, present.id, element.id]);
const keyframes: VisualAnimation["keyframes"] = element.animation.keyframes.at(-1)?.atFrame === durationFrames
? element.animation.keyframes
: [...element.animation.keyframes, {
atFrame: durationFrames,
style: element.animation.keyframes.at(-1)!.style,
}];
const frames = keyframes.map((keyframe) => {
const easing = keyframe.easing === undefined ? "" : `;animation-timing-function:${keyframe.easing}`;
return `${percentage(keyframe.atFrame, durationFrames)}{${css(keyframe.style)}${easing}}`;
}).join("");
return [`@keyframes ${name}{${frames}}`];
});
}
function orderedVisualPresents(tracks: readonly Track[]): Array<{ readonly track: VisualTrack; readonly present: VisualPresent }> {
return tracks
.filter((track): track is VisualTrack => track.kind === "visual")
.flatMap((track) => track.presents.map((present) => ({ track, present })))
.sort((left, right) => left.present.z - right.present.z
|| left.track.id.localeCompare(right.track.id)
|| left.present.order - right.present.order
|| left.present.id.localeCompare(right.present.id));
}
function mergeFrameSpans(spans: readonly HtmlFrameSpan[]): HtmlFrameSpan[] {
const result: HtmlFrameSpan[] = [];
for (const span of [...spans].sort((left, right) => left.startFrame - right.startFrame
|| left.endFrameExclusive - right.endFrameExclusive)) {
const previous = result.at(-1);
if (previous !== undefined && span.startFrame <= previous.endFrameExclusive) {
result[result.length - 1] = {
startFrame: previous.startFrame,
endFrameExclusive: Math.max(previous.endFrameExclusive, span.endFrameExclusive),
};
} else result.push({ ...span });
}
return result;
}
function collectArtifacts(composition: Composition): HtmlArtifact[] {
const artifacts = new Map<ResourceId, { artifact: BlobRef; always: boolean; spans: HtmlFrameSpan[] }>();
const add = (artifact: Pick<BlobRef, "resource" | "size" | "mediaType">,
usage: "always" | HtmlFrameSpan): void => {
const next: BlobRef = {
kind: "blob",
resource: artifact.resource,
size: artifact.size,
mediaType: artifact.mediaType,
};
const existing = artifacts.get(artifact.resource);
if (existing !== undefined && (existing.artifact.size !== next.size || existing.artifact.mediaType !== next.mediaType)) {
throw new Error(`HTML renderer Artifact ${artifact.resource} has conflicting metadata.`);
}
const entry = existing ?? { artifact: next, always: false, spans: [] };
if (usage === "always") entry.always = true;
else if (!entry.always) entry.spans.push({ ...usage });
artifacts.set(artifact.resource, entry);
};
for (const track of composition.tracks) {
if (track.kind === "audio") continue;
for (const present of track.presents) {
for (const element of present.elements) {
if (element.kind === "image" || element.kind === "video") add(element.artifact, present.span);
if (element.kind === "surface") add(element.surface.artifact, present.span);
// HtmlVisual HTML, CSS and setup are intentionally opaque. Their
// declared dependencies stay conservative even though the visual root
// itself has a Present span.
if (element.kind === "program") for (const artifact of element.program.artifacts) add(artifact, "always");
if (element.kind === "text") {
for (const font of element.fonts ?? []) {
// @font-face declarations live at document scope. Keep them whole
// rather than infer browser font demand from text structure.
for (const source of font.sources) add(source.artifact, "always");
}
}
if (element.kind === "text-flow" || element.kind === "path-text") {
for (const font of collectTerminalTextFonts(element)) {
for (const source of font.sources) add(source.artifact, "always");
}
}
}
}
}
return [...artifacts.values()].map(({ artifact, always, spans }) => ({
artifact,
usage: always ? { kind: "always" as const } : { kind: "frames" as const, spans: mergeFrameSpans(spans) },
})).sort((left, right) => left.artifact.resource.localeCompare(right.artifact.resource));
}
function collectSurfaces(composition: Composition): CompositableSurfaceRef[] {
const surfaces = new Map<ResourceId, CompositableSurfaceRef>();
for (const track of composition.tracks) {
if (track.kind !== "visual") continue;
for (const present of track.presents) {
for (const element of present.elements) {
if (element.kind !== "surface") continue;
const surface = structuredClone(element.surface);
const existing = surfaces.get(surface.artifact.resource);
if (existing !== undefined && canonicalStringify(existing) !== canonicalStringify(surface)) {
throw new Error(`HTML renderer Surface ${surface.artifact.resource} has conflicting declarations.`);
}
surfaces.set(surface.artifact.resource, surface);
}
}
}
return [...surfaces.values()].sort((left, right) =>
left.artifact.resource.localeCompare(right.artifact.resource));
}
function collectFonts(composition: Composition): FontArtifactRef[] {
const fonts = new Map<string, FontArtifactRef>();
for (const track of composition.tracks) {
if (track.kind !== "visual") continue;
for (const present of track.presents) {
for (const element of present.elements) {
if (element.kind !== "text") continue;
for (const font of element.fonts ?? []) fonts.set(canonicalStringify(font), font);
}
}
}
for (const track of composition.tracks) {
if (track.kind !== "visual") continue;
for (const present of track.presents) {
for (const element of present.elements) {
if (element.kind !== "text-flow" && element.kind !== "path-text") continue;
for (const font of collectTerminalTextFonts(element)) fonts.set(canonicalStringify(font), font);
}
}
}
return [...fonts.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, font]) => font);
}
function fontFormat(mediaType: string): string {
if (mediaType === "font/woff2") return "woff2";
if (mediaType === "font/woff") return "woff";
if (mediaType === "font/otf") return "opentype";
return "truetype";
}
function renderFontFaces(composition: Composition, stableId: StableDomId): string {
return collectFonts(composition).flatMap((font) => font.sources.map((source) => [
"@font-face{",
`font-family:${exactFontFamily(font, stableId)};`,
`src:url(\"${htmlProgramResourceUri(source.artifact.resource)}\") format(\"${fontFormat(source.artifact.mediaType)}\");`,
`font-weight:${font.weight};`,
`font-style:${font.style};`,
"font-display:block;",
...(source.unicodeRange === undefined ? [] : [`unicode-range:${source.unicodeRange};`]),
"}",
].join(""))).join("\n ");
}
function hasTerminalText(composition: Composition): boolean {
return composition.tracks.some((track) => track.kind === "visual"
&& track.presents.some((present) => present.elements.some((element) =>
element.kind === "text-flow" || element.kind === "path-text")));
}
function hasFrameAnimations(composition: Composition): boolean {
return composition.tracks.some((track) => track.kind === "visual"
&& track.presents.some((present) => present.elements.some((element) => element.animation !== undefined)));
}
function frameAnimationRuntime(numerator: number, denominator: number): string {
return String.raw`
(() => {
const numerator = ${numerator};
const denominator = ${denominator};
const millisecondsPerFrame = denominator * 1000 / numerator;
const groupsBySpan = new Map();
for (const element of document.querySelectorAll("[data-hypit-frame-animation]")) {
const start = Number(element.getAttribute("data-hypit-animation-start-frame"));
const duration = Number(element.getAttribute("data-hypit-animation-sample-frames"));
if (!Number.isSafeInteger(start) || !Number.isSafeInteger(duration) || start < 0 || duration <= 0) {
throw new Error("Visual IR frame animation has an invalid Present span.");
}
const end = start + duration;
if (!Number.isSafeInteger(end)) throw new Error("Visual IR frame animation Present span exceeds safe arithmetic.");
// CSS already keeps every authored animation paused. Only materialize the
// browser Animation objects which this render can actually sample.
if (!htmlSelectionOverlaps(start, end)) continue;
void element.getBoundingClientRect();
const animation = element.getAnimations()[0];
if (animation === undefined) throw new Error("Visual IR frame animation did not materialize.");
// The authored keyframes are already the compact state function. Keep them
// instead of expanding every Present frame into a second table of
// computed-style strings in every render Worker, but do not leave the CSS
// animation live: HTML renderer' css and waapi adapters seek every live
// document animation to absolute composition time, which replaces this
// Present-relative pose whenever the Present does not start at frame 0.
const keyframes = animation.effect.getKeyframes();
const timing = animation.effect.getTiming();
const properties = [...new Set(keyframes.flatMap((keyframe) => Object.keys(keyframe)))]
.filter((name) => name !== "offset" && name !== "computedOffset" && name !== "easing" && name !== "composite");
animation.cancel();
element.style.animationName = "none";
const key = start + ":" + end;
let work = groupsBySpan.get(key);
if (work === undefined) {
work = {
startFrame: start,
endFrameExclusive: end,
order: groupsBySpan.size,
payload: { animations: [] },
};
groupsBySpan.set(key, work);
}
work.payload.animations.push({ element, keyframes, timing, properties });
}
// The shared index owns only frame-span lookup. Animation materialization and
// absolute currentTime evaluation remain private to this adapter.
const workIndex = htmlCreateFrameWorkIndex([...groupsBySpan.values()]);
const read = (style, name) => name.startsWith("--") ? style.getPropertyValue(name) : style[name];
const write = (style, name, value) => {
if (name.startsWith("--")) style.setProperty(name, value);
else style[name] = value;
};
const applyFrame = (programFrame) => {
const active = [];
for (const work of workIndex.at(programFrame)) {
const localTime = (programFrame - work.startFrame) * millisecondsPerFrame;
// Always derive the pose from the absolute requested frame. Worker
// partitioning, seek order and the previously rendered frame are not
// inputs to animation state.
for (const item of work.payload.animations) active.push({ item, localTime });
}
// Evaluate each pose with a transient Animation, read it and cancel it before
// this seek returns, so no adapter ever sees it. The Animation constructor,
// unlike Element.animate, is not tracked by HTML renderer' waapi adapter. Only
// the resulting inline style reaches the captured frame.
const probes = active.map(({ item, localTime }) => {
const probe = new Animation(new KeyframeEffect(item.element, item.keyframes, item.timing), document.timeline);
probe.currentTime = localTime;
return probe;
});
const poses = active.map(({ item }) => {
const style = getComputedStyle(item.element);
return item.properties.map((name) => read(style, name));
});
for (const probe of probes) probe.cancel();
active.forEach(({ item }, index) => {
item.properties.forEach((name, position) => write(item.element.style, name, poses[index][position]));
});
void document.documentElement.getBoundingClientRect();
};
void document.documentElement.getBoundingClientRect();
window.addEventListener("hypit-frame", (event) => applyFrame(event.detail?.frame));
})();`;
}
function frameProgramRuntime(frameCount: number): string {
return `(() => {
const presents = [...document.querySelectorAll('[data-hypit-present-start-frame]')].map(element => ({
element,
startFrame: Number(element.getAttribute('data-hypit-present-start-frame')),
endFrameExclusive: Number(element.getAttribute('data-hypit-present-end-frame')),
}));
const applyFrame = async frame => {
if (!Number.isSafeInteger(frame) || frame < 0 || frame >= ${frameCount}) {
throw new Error('HTML Program frame is outside its domain.');
}
for (const present of presents) {
present.element.style.display = frame >= present.startFrame && frame < present.endFrameExclusive ? '' : 'none';
}
const pending = [];
window.dispatchEvent(new CustomEvent('hypit-frame', { detail: {
frame,
waitUntil(value) { pending.push(Promise.resolve(value)); },
}}));
await Promise.all(pending);
void document.documentElement.getBoundingClientRect();
};
Object.defineProperty(window, '__hypitFrameProgram', { configurable: false, writable: false, value: Object.freeze({
frameCount: ${frameCount},
async prepare() { await document.fonts.ready; await applyFrame(0); },
applyFrame,
}) });
})();`;
}
function emitHtml(composition: Composition, timeline: Timeline, frameSources: HtmlFrameSource[]): string {
const { numerator, denominator } = timeline.frameRate;
const visuals = orderedVisualPresents(composition.tracks);
// One document, one set of glyph filter definitions. Keep definitions outside
// temporal Present roots so a render can make an unrelated Present inert
// without invalidating a selected Present's document-wide url(#id) reference.
const emittedFilterIds = new Set<string>();
const sharedGlyphFilterDefinitions: string[] = [];
const stableId = createStableDomId();
const visualHtml = visuals.map(({ track, present }, index) => renderVisualPresent(track, present, index,
numerator, denominator, emittedFilterIds, sharedGlyphFilterDefinitions, stableId, frameSources)).join("\n ");
const sharedDefinitionsHtml = sharedGlyphFilterDefinitions.length === 0 ? ""
: `<svg data-hypit-document-definitions aria-hidden="true" width="0" height="0" style="position:absolute;overflow:hidden"><defs>${sharedGlyphFilterDefinitions.join("")}</defs></svg>`;
const animationCss = visuals.flatMap(({ track, present }) => renderAnimationRules(track, present, stableId)).join("\n ");
const fontCss = renderFontFaces(composition, stableId);
const programs = visuals.flatMap(({ track, present }) => present.elements.flatMap(element => element.kind !== "program" ? [] : [{
id: stableId([track.id, present.id, element.id]),
startFrame: present.span.startFrame,
durationFrames: present.span.endFrameExclusive - present.span.startFrame,
program: readHtmlVisual(element.program),
}]));
const programCss = programs.map(entry => `@scope (#${entry.id}) { ${entry.program.css ?? ""} }`).join("\n");
const hasVisibility = visuals.some(({ present }) => present.visibility !== undefined);
const programRuntime = programs.length === 0 ? "" : `<script>${htmlVisualScript(programs, numerator, denominator)}</script>`;
const visibilityRuntime = hasVisibility ? `<script>${presentationVisibilityScript(numerator, denominator)}</script>` : "";
const duration = frameSeconds(timelineFrameCount(timeline), numerator, denominator);
const fps = fpsRational(numerator, denominator);
const frameCount = timelineFrameCount(timeline);
const needsFrameWork = hasFrameAnimations(composition) || hasTerminalText(composition) || programs.length > 0 || hasVisibility;
const frameRuntime = `\n <script>\n ${needsFrameWork ? frameWorkIndexRuntime : frameSelectionRuntime}\n </script>
<script>${presentationCaptureScopeRuntime}</script>${hasFrameAnimations(composition) || hasTerminalText(composition)
? `\n <script>${hasFrameAnimations(composition) ? `\n ${frameAnimationRuntime(numerator, denominator)}` : ""}${hasTerminalText(composition) ? `\n ${terminalTextLayoutScript}` : ""}\n </script>`
: ""}`;
return `<!doctype html>
<html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width,initial-scale=1"/>
<style>
html,body{margin:0;width:100%;height:100%;overflow:hidden;background:${composition.canvas.clearColor}}
[data-hypit-program-root]{position:relative;overflow:hidden;background:${composition.canvas.clearColor}}
*,*::before,*::after{box-sizing:border-box}
${fontCss}
${animationCss}
${programCss}
</style>
</head>
<body>
<div data-hypit-program-root data-hypit-program-id="${escapeHtml(composition.id)}" data-hypit-width="${composition.canvas.width}" data-hypit-height="${composition.canvas.height}" data-hypit-frame-numerator="${numerator}" data-hypit-frame-denominator="${denominator}" data-hypit-frame-count="${frameCount}" style="width:${composition.canvas.width}px;height:${composition.canvas.height}px">
${sharedDefinitionsHtml}${sharedDefinitionsHtml.length === 0 ? "" : "\n "}${visualHtml}
</div>${frameRuntime}${programRuntime}
${visibilityRuntime}
<script>${frameProgramRuntime(frameCount)}</script>
</body>
</html>
`;
}
function normalizedDocument(value: HtmlProgram): HtmlProgram {
return {
visualIr: value.visualIr,
frameRate: { ...value.frameRate },
frameCount: value.frameCount,
canvas: { ...value.canvas },
artifacts: [...value.artifacts]
.map((entry) => ({ artifact: { ...entry.artifact }, usage: entry.usage.kind === "always"
? { kind: "always" as const }
: { kind: "frames" as const, spans: entry.usage.spans.map((span) => ({ ...span })) } }))
.sort((left, right) => left.artifact.resource.localeCompare(right.artifact.resource)),
surfaces: [...value.surfaces]
.map((surface) => structuredClone(surface))
.sort((left, right) => left.artifact.resource.localeCompare(right.artifact.resource)),
frameSources: [...value.frameSources].map((source) => ({
...source,
sourceFrame: { ...source.sourceFrame },
sourceRate: { ...source.sourceRate },
sourceFrameRate: { ...source.sourceFrameRate },
})).sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id)),
html: value.html,
};
}
export function compileHtmlProgram(composition: Composition, timeline: Timeline): HtmlProgram {
assertCompositionIdentity(composition, timeline);
const frameSources: HtmlFrameSource[] = [];
const content = normalizedDocument({
visualIr: VISUAL_IR_V1,
frameRate: { ...timeline.frameRate },
frameCount: timelineFrameCount(timeline),
canvas: {
width: composition.canvas.width,
height: composition.canvas.height,
},
artifacts: collectArtifacts(composition),
surfaces: collectSurfaces(composition),
frameSources,
html: emitHtml(composition, timeline, frameSources),
});
return content;
}
export function assertHtmlProgram(document: HtmlProgram): void {
if (document.visualIr !== VISUAL_IR_V1) throw new Error("Unsupported HtmlProgram visual IR.");
if (
!Number.isSafeInteger(document.frameRate.numerator)
|| document.frameRate.numerator <= 0
|| !Number.isSafeInteger(document.frameRate.denominator)
|| document.frameRate.denominator <= 0
|| !Number.isSafeInteger(document.frameCount)
|| document.frameCount <= 0
|| !Number.isSafeInteger(document.canvas.width)
|| document.canvas.width <= 0
|| !Number.isSafeInteger(document.canvas.height)
|| document.canvas.height <= 0
) {
throw new Error("HtmlProgram frame domain or canvas is invalid.");
}
if (!document.html.startsWith("<!doctype html>")) throw new Error("HtmlProgram HTML is invalid.");
const declared = [...document.artifacts];
if (declared.some((entry) => {
const item = entry?.artifact;
if (item?.kind !== "blob" || !isResourceId(item.resource)
|| !Number.isSafeInteger(item.size) || item.size < 0 || item.mediaType.length === 0) return true;
if (entry.usage?.kind === "always") return Object.keys(entry.usage).length !== 1;
if (entry.usage?.kind !== "frames" || !Array.isArray(entry.usage.spans) || entry.usage.spans.length === 0) return true;
if (entry.usage.spans.some((span) => span === null || typeof span !== "object"
|| !Number.isSafeInteger(span.startFrame) || !Number.isSafeInteger(span.endFrameExclusive)
|| span.startFrame < 0 || span.endFrameExclusive <= span.startFrame
|| span.endFrameExclusive > document.frameCount)) return true;
return JSON.stringify(mergeFrameSpans(entry.usage.spans)) !== JSON.stringify(entry.usage.spans);
}) || new Set(declared.map((entry) => entry.artifact.resource)).size !== declared.length) {
throw new Error("HtmlProgram Artifact set is invalid.");
}
const referenced = [...document.html.matchAll(RESOURCE_URI)].map((match) => match[1] as ResourceId);
const actual = [...new Set(referenced)].sort();
if (JSON.stringify(actual) !== JSON.stringify(declared.map((entry) => entry.artifact.resource).sort())) {
throw new Error("HtmlProgram Artifact placeholders do not match its declared dependencies.");
}
if (!Array.isArray(document.surfaces)) throw new Error("HtmlProgram Surface set is invalid.");
if (!Array.isArray(document.frameSources) || document.frameSources.some((source) =>
typeof source?.id !== "string" || source.id.length === 0 || !isResourceId(source.resource)
|| !Number.isSafeInteger(source.startFrame) || !Number.isSafeInteger(source.endFrameExclusive)
|| source.startFrame < 0 || source.endFrameExclusive <= source.startFrame
|| source.endFrameExclusive > document.frameCount
|| !Number.isSafeInteger(source.sourceFrame?.numerator) || source.sourceFrame.numerator < 0
|| !Number.isSafeInteger(source.sourceFrame?.denominator) || source.sourceFrame.denominator <= 0
|| !Number.isSafeInteger(source.sourceRate?.numerator)
|| !Number.isSafeInteger(source.sourceRate?.denominator) || source.sourceRate.denominator <= 0
|| !Number.isSafeInteger(source.sourceFrameRate?.numerator) || source.sourceFrameRate.numerator <= 0
|| !Number.isSafeInteger(source.sourceFrameRate?.denominator) || source.sourceFrameRate.denominator <= 0
|| !declared.some((entry) => entry.artifact.resource === source.resource))) {
throw new Error("HtmlProgram frame-source plan is invalid.");
}
if (new Set(document.frameSources.map((source) => source.id)).size !== document.frameSources.length) {
throw new Error("HtmlProgram frame-source identities must be unique.");
}
const surfaceArtifacts = new Set<string>();
for (const [index, surface] of document.surfaces.entries()) {
assertCompositableSurfaceRef(surface, `HtmlProgram.surfaces.${index}`);
if (surfaceArtifacts.has(surface.artifact.resource)) {
throw new Error("HtmlProgram Surface set repeats an Artifact.");
}
surfaceArtifacts.add(surface.artifact.resource);
const artifact = declared.find((entry) => entry.artifact.resource === surface.artifact.resource)?.artifact;
if (artifact === undefined
|| artifact.size !== surface.artifact.size
|| artifact.mediaType !== surface.artifact.mediaType) {
throw new Error("HtmlProgram Surface is not bound to its declared Artifact.");
}
}
const referencedSurfaces = [...new Set(
[...document.html.matchAll(SURFACE_RESOURCE)].map((match) => match[1]!),
)].sort();
if (JSON.stringify(referencedSurfaces) !== JSON.stringify([...surfaceArtifacts].sort())) {
throw new Error("HtmlProgram Surface markers do not match its typed dependencies.");
}
}
/** Validate one independently renderable frame index without parsing generated HTML. */
export function assertHtmlFrameIndex(document: HtmlProgram, frame: number): void {
assertHtmlProgram(document);
if (!Number.isSafeInteger(frame) || frame < 0 || frame >= document.frameCount) {
throw new Error(`HTML renderer frame ${frame} is outside [0, ${document.frameCount}).`);
}
}
/** Validate a Provider-owned half-open chunk of the document's exact frame domain. */
export function assertHtmlFrameSpan(
document: HtmlProgram,
span: HtmlFrameSpan,
): void {
assertHtmlProgram(document);
if (
!Number.isSafeInteger(span.startFrame)
|| !Number.isSafeInteger(span.endFrameExclusive)
|| span.startFrame < 0
|| span.endFrameExclusive <= span.startFrame
|| span.endFrameExclusive > document.frameCount
) {
throw new Error(
`HTML renderer frame span [${span.startFrame}, ${span.endFrameExclusive}) is outside [0, ${document.frameCount}).`,
);
}
}
function assertHTMLFrameSelection(
document: HtmlProgram,
selection: readonly HtmlFrameSpan[],
): void {
if (selection.length === 0) throw new Error("HTML renderer Artifact selection must not be empty");
let previousEnd = 0;
for (const [index, span] of selection.entries()) {
if (span === null || typeof span !== "object"
|| !Number.isSafeInteger(span.startFrame) || !Number.isSafeInteger(span.endFrameExclusive)
|| span.startFrame < 0 || span.endFrameExclusive <= span.startFrame
|| span.endFrameExclusive > document.frameCount
|| (index > 0 && span.startFrame < previousEnd)) {
throw new Error("HTML renderer Artifact selection must contain ordered, disjoint spans inside the document frame domain");
}
previousEnd = span.endFrameExclusive;
}
}
function artifactUsageOverlaps(
usage: readonly HtmlFrameSpan[],
selection: readonly HtmlFrameSpan[],
): boolean {
return usage.some((span) => {
let low = 0;
let high = selection.length;
while (low < high) {
const middle = low + Math.floor((high - low) / 2);
if (selection[middle]!.endFrameExclusive <= span.startFrame) low = middle + 1;
else high = middle;
}
return low < selection.length && selection[low]!.startFrame < span.endFrameExclusive;
});
}
/**
* Project one whole render selection onto the compiler's conservative byte dependencies.
* The result is shared by every worker; no worker or traversal state enters the proof.
*/
export function selectHtmlArtifacts(
document: HtmlProgram,
frameSelection?: readonly HtmlFrameSpan[],
): readonly HtmlArtifact[] {
assertHtmlProgram(document);
if (frameSelection === undefined) return document.artifacts;
assertHTMLFrameSelection(document, frameSelection);
return document.artifacts.filter((entry) => entry.usage.kind === "always"
|| artifactUsageOverlaps(entry.usage.spans, frameSelection));
}
/** Runtime-only URL materialization. The returned HTML is intentionally not a new compiled Record. */
export function materializeHtmlProgram(
document: HtmlProgram,
resolve: ResourceUrlResolver,
): string {
assertHtmlProgram(document);
const artifacts = new Map(document.artifacts.map((entry) => [entry.artifact.resource, entry.artifact]));
return document.html.replace(RESOURCE_URI, (_uri, resource: ResourceId) => {
const artifact = artifacts.get(resource);
if (artifact === undefined) throw new Error(`HTML renderer Resource ${resource} is undeclared.`);
return escapeHtml(resolve(artifact));
});
}
export const htmlProgramTime = { frameSeconds, fpsDecimal, fpsRational } as const;