Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import type { LintContext, HyperframeLintFinding, OpenTag } from "../context";
import { readDecodedAttr, truncateSnippet } from "../utils";
import {
isSubCompositionHost,
topLevelElements,
trackKindOf,
type StructureNode,
} from "@hyperframes/parsers/top-level-elements";
import { readClipTiming } from "@hyperframes/parsers/composition-contract";
import { readDataDurationSeconds } from "@hyperframes/parsers/media-duration";
import { TIMING_TOLERANCE_SECONDS } from "@hyperframes/parsers/composition-duration";
interface TagNode extends StructureNode<TagNode> {
children: TagNode[];
open: OpenTag;
}
// Text-level tags may sit inside a timed element without being "nested structure".
const INLINE_TEXT_TAGS = new Set([
"br",
"wbr",
"b",
"i",
"u",
"s",
"em",
"strong",
"small",
"sub",
"sup",
"mark",
"span",
"a",
"code",
"abbr",
]);
// Their content is one drawn object, so their children are not layout.
const OPAQUE_TAGS = new Set([
"svg",
"canvas",
"picture",
"video",
"audio",
"select",
"textarea",
"iframe",
"object",
]);
// Never layout: their content is code or inert markup.
const NON_LAYOUT_TAGS = new Set(["style", "script", "template", "noscript"]);
// Media has a default length (the file's, or the dropped-image default), so data-start alone is enough.
const MEDIA_TAGS = new Set(["video", "audio", "img"]);
const NODE_ATTRS = [
"id",
"class",
"data-start",
"data-duration",
"data-end",
"data-track",
"data-track-index",
"data-track-kind",
"data-composition-id",
"data-composition-src",
"data-hf-media-start-basis",
];
function toNode(open: OpenTag): TagNode {
const attrs: Record<string, string | undefined> = {};
for (const name of NODE_ATTRS) attrs[name] = readDecodedAttr(open.raw, name) ?? undefined;
return { tag: open.name, attrs, children: [], open };
}
type OpenNode = { node: TagNode; end: number };
/** The innermost still-open node at `index`; closes nodes the index has passed. */
function enclosing(stack: OpenNode[], root: TagNode, index: number): TagNode {
let top = stack.at(-1);
while (top && stack.length > 1 && index >= top.end) {
stack.pop();
top = stack.at(-1);
}
return top?.node ?? root;
}
/** Rebuilds nesting from the flat tag list using each tag's close index. */
function buildTree(ctx: LintContext): TagNode | null {
const { rootTag } = ctx;
const rootEnd = rootTag?.closeIndex;
if (!rootTag || rootEnd == null) return null;
const root = toNode(rootTag);
const stack: OpenNode[] = [{ node: root, end: rootEnd }];
for (const tag of ctx.tags.filter((t) => t.index > rootTag.index && t.index < rootEnd)) {
const node = toNode(tag);
enclosing(stack, root, tag.index).children.push(node);
if (tag.closeIndex != null) stack.push({ node, end: tag.closeIndex });
}
return root;
}
function hasNestedStructure(node: TagNode): TagNode | null {
if (OPAQUE_TAGS.has(node.tag)) return null;
for (const child of node.children) {
if (NON_LAYOUT_TAGS.has(child.tag)) continue;
if (!INLINE_TEXT_TAGS.has(child.tag)) return child;
const deeper = hasNestedStructure(child);
if (deeper) return deeper;
}
return null;
}
const describe = (node: TagNode) => `<${node.tag}${node.attrs.id ? ` id="${node.attrs.id}"` : ""}>`;
type Severity = HyperframeLintFinding["severity"];
function nestedStructureFindings(rows: TagNode[], severity: Severity): HyperframeLintFinding[] {
return rows.flatMap((row) => {
const nested = isSubCompositionHost(row) ? null : hasNestedStructure(row);
if (!nested) return [];
return [
{
code: "nested_structure_needs_subcomposition",
severity,
message: `${describe(row)} is a timeline element that contains nested ${describe(nested)}. The timeline shows one row per top-level element, and the root composition is built only from sub-compositions.`,
elementId: row.attrs.id,
fixHint: `Move ${describe(row)} and its contents into a sub-composition file and mount it with data-composition-src.`,
},
];
});
}
function missingDurationFindings(rows: TagNode[], severity: Severity): HyperframeLintFinding[] {
return rows
.filter(
(row) =>
!MEDIA_TAGS.has(row.tag) &&
row.attrs["data-duration"] === undefined &&
row.attrs["data-end"] === undefined &&
!isSubCompositionHost(row),
)
.map((row) => ({
code: "timeline_element_missing_timing",
severity,
message: `${describe(row)} is a timeline element without data-duration, so the timeline cannot draw where it ends.`,
elementId: row.attrs.id,
fixHint: `Add data-duration (in seconds) to ${describe(row)}.`,
}));
}
function captionFindings(rows: TagNode[], severity: Severity): HyperframeLintFinding[] {
const captionRows = rows.filter((row) => trackKindOf(row).kind === "captions");
const findings: HyperframeLintFinding[] = captionRows
.filter((row) => trackKindOf(row).source === "legacy-captions")
.map((row) => ({
code: "caption_track_kind_missing",
severity,
message: `${describe(row)} looks like captions but is not marked as such, so the timeline cannot group it on the caption track.`,
elementId: row.attrs.id,
fixHint: `Add data-track-kind="captions" to ${describe(row)}.`,
}));
const lanes = new Set(
captionRows.flatMap((row) => row.attrs["data-track-index"] ?? row.attrs["data-track"] ?? []),
);
if (lanes.size > 1) {
findings.push({
code: "multiple_caption_tracks",
severity,
message: `Captions are spread across ${lanes.size} timeline tracks. Keep all captions on one track.`,
fixHint: "Give every caption element the same data-track-index.",
});
}
return findings;
}
const hundredths = (seconds: number) => Math.round(seconds * 100) / 100;
function clipsPastRootFindings(root: TagNode, rows: TagNode[]): HyperframeLintFinding[] {
if (root.attrs["data-composition-id"] === undefined) return [];
const rootDuration = readDataDurationSeconds((name) => root.attrs[name]);
if (rootDuration === null) return [];
const limit = hundredths(rootDuration);
return rows.flatMap((row) => {
const { start, end } = readClipTiming({ getAttribute: (name) => row.attrs[name] ?? null });
if (start === null || end === null || end <= rootDuration + TIMING_TOLERANCE_SECONDS) return [];
return [
{
code: "clip_ends_past_root_duration",
severity: "warning",
message: `${describe(row)} runs from ${hundredths(start)}s to ${hundredths(end)}s, past the root composition's data-duration of ${limit}s, so it is cut off in previews, posters and renders.`,
elementId: row.attrs.id,
fixHint: `Extend the root data-duration to ${hundredths(end)}, or make ${describe(row)} end at or before ${limit}s.`,
snippet: truncateSnippet(row.open.raw),
},
];
});
}
function followsParentVisibility(clip: TagNode): boolean {
return clip.tag !== "audio" && clip.attrs["data-hf-media-start-basis"] !== "global";
}
function isTimed(timing: {
start: number | null;
end: number | null;
}): timing is { start: number; end: number } {
return timing.start !== null && timing.end !== null;
}
/** The runtime shows a nested clip only while its parent shows, and both data-starts count from the composition. */
function neverVisibleNestedFindings(parent: TagNode, severity: Severity): HyperframeLintFinding[] {
const window = readClipTiming({ getAttribute: (name) => parent.attrs[name] ?? null });
return topLevelElements(parent).flatMap((clip) => {
const inner = isSubCompositionHost(clip) ? [] : neverVisibleNestedFindings(clip, severity);
const own = readClipTiming({ getAttribute: (name) => clip.attrs[name] ?? null });
if (!followsParentVisibility(clip) || !isTimed(window) || !isTimed(own)) return inner;
if (own.end > window.start && own.start < window.end) return inner;
const shows = `${hundredths(window.start)}s to ${hundredths(window.end)}s`;
return [
{
code: "nested_clip_never_visible",
severity,
message: `${describe(clip)} plays from ${hundredths(own.start)}s to ${hundredths(own.end)}s, but it sits inside ${describe(parent)}, which only shows from ${shows}, so it never appears. A nested data-start counts from the composition's start, not from ${describe(parent)}.`,
elementId: clip.attrs.id,
fixHint: `Give ${describe(clip)} a data-start between ${shows} in composition time, or move it out of ${describe(parent)}.`,
snippet: truncateSnippet(clip.open.raw),
},
...inner,
];
});
}
export const structureRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
(ctx) => {
// The timeline shows the root composition's rows; a sub-composition file is the leaf where layout lives.
if (ctx.options.isSubComposition) return [];
const root = buildTree(ctx);
if (!root) return [];
const severity = ctx.options.host === "studio" ? "error" : "warning";
const rows = topLevelElements(root);
return [
...nestedStructureFindings(rows, severity),
...missingDurationFindings(rows, severity),
...captionFindings(rows, severity),
...clipsPastRootFindings(root, rows),
];
},
(ctx) => {
const root = buildTree(ctx);
if (!root) return [];
const severity = ctx.options.host === "studio" ? "error" : "warning";
return topLevelElements(root)
.filter((row) => !isSubCompositionHost(row))
.flatMap((row) => neverVisibleNestedFindings(row, severity));
},
];