Files
hyperframes/packages/lint/src/rules/composition.ts
T
Miguel Ángel 571c99ce9e fix(sdk): read a composition's variables from its root when its html has none (#4454)
* fix(sdk): read a composition's variables from its root when its html has none

* fix: composition metadata and lint also read variables declared on the root

* fix(sdk): keep root declarations on the root through undo and prefer them like the runtime

* fix(sdk): read variables from both <html> and the root, editing each where declared
2026-09-25 00:14:11 -04:00

1641 lines
77 KiB
TypeScript

import type { LintContext, HyperframeLintFinding, ExtractedBlock, OpenTag } from "../context";
import {
findHtmlTag,
readAttr,
readDecodedAttr,
readJsonAttr,
stripCssComments,
stripJsComments,
stripJsCode,
truncateSnippet,
WINDOW_TIMELINE_ASSIGN_PATTERN,
} from "../utils";
import { COMPOSITION_VARIABLE_TYPES, isSafeMediaUrl } from "@hyperframes/parsers/composition";
import { COMPOSITION_ATTRIBUTES, readClipTiming } from "@hyperframes/parsers/composition-contract";
import { resolveCompositionDuration } from "@hyperframes/parsers/composition-duration";
import {
readAuthoredDurationSeconds,
resolveMediaDuration,
type MediaTag,
} from "@hyperframes/parsers/media-duration";
// Agent guidance thresholds: warning-only nudges for files/tracks that become hard
// to inspect and revise reliably in a single composition.
// packages/cli/src/utils/compositionViewport.ts MAX_VIEWPORT_DIMENSION. Kept as a
// literal rather than imported: @hyperframes/lint must not depend on the CLI, and
// the number is a property of the capture path we are warning about, not of lint.
const INSPECTION_VIEWPORT_CAP = 4096;
const MAX_COMPOSITION_LINES = 300;
const MAX_TIMED_ELEMENTS_PER_TRACK = 3;
const TRACK_DENSITY_EXEMPT_TAGS = new Set(["audio", "script", "style", "video"]);
const CAPTION_CUE_TOKEN =
/^(?:caption(?:[-_](?:group|word|line|block|cue|text))?|subtitle(?:[-_](?:group|line|cue|text))?|cg-.+)$/i;
// composition_heavy_overlay_count_high — warn when a composition carries this
// many or more elements whose CSS uses filter:blur, clip-path (non-none), or
// radial-gradient. Field signal ts=1784040753 (#hyperframes-cli-feedback):
// a composition with ~40 such elements captures solid-black for the first
// ~half of the render, recovering near the end. Presence alone matters —
// opacity:0 and visibility:hidden overlays still contribute — so the rule
// counts every one that isn't display:none-hidden. Threshold sits below the
// observed 40-element repro (25) so authors get lead time; adjust here if
// noise/signal shifts, since a per-rule config option would also require
// plumbing through HyperframeLinterOptions across every embedder.
const HEAVY_OVERLAY_ELEMENT_COUNT_WARN = 25;
const HEAVY_OVERLAY_EXEMPT_TAGS = new Set([
"audio",
"body",
"br",
"defs",
"head",
"hr",
"html",
"link",
"meta",
"script",
"source",
"style",
"template",
"title",
"use",
"video",
]);
// Matches any of: `filter: <...>blur(...)`, `clip-path: <non-none-value>`,
// or `radial-gradient(...)`. Property terminator is `;` or `}`; value class
// excludes both so we don't over-match into the next declaration. `clip-path`
// escapes when its value starts with a CSS-wide keyword that leaves the render
// tree unaffected (none / inherit / initial / unset) — the whitespace-eating
// `\s*` lives *inside* the negative lookahead so the engine can't backtrack
// `\s*` from outside to 0-width and slip past the keyword guard.
const HEAVY_OVERLAY_CSS_PATTERN =
/(?:filter\s*:[^;}]*\bblur\s*\()|(?:clip-path\s*:(?!\s*(?:none|inherit|initial|unset)\b)\s*[^;}]+)|(?:radial-gradient\s*\()/i;
const INLINE_STYLE_DISPLAY_NONE_PATTERN = /(?:^|;)\s*display\s*:\s*none\b/i;
function readTagTiming(rawTag: string) {
return readClipTiming({ getAttribute: (name) => readAttr(rawTag, name) });
}
function countPhysicalLines(source: string): number {
if (source.length === 0) return 0;
const normalized = source.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
const withoutFinalNewline = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
return withoutFinalNewline.split("\n").length;
}
function countStructuralLines(source: string): number {
return countPhysicalLines(source.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "<style></style>"));
}
function isCaptionCue(tag: OpenTag): boolean {
const classTokens = (readAttr(tag.raw, "class") || "").split(/\s+/).filter(Boolean);
const id = readAttr(tag.raw, "id");
return (
classTokens.some((token) => CAPTION_CUE_TOKEN.test(token)) ||
Boolean(id && CAPTION_CUE_TOKEN.test(id))
);
}
export function isRegistrySourceFile(filePath?: string): boolean {
if (!filePath) return false;
const normalized = filePath.replace(/\\/g, "/");
return /(?:^|\/)registry\/blocks\/([^/]+)\/\1\.html$/i.test(normalized);
}
export function isRegistryInstalledFile(rawSource: string): boolean {
return /^\s*<!--\s*hyperframes-registry-item:[^>]*-->/i.test(rawSource.slice(0, 512));
}
function isCompositionRootOrMount(rawTag: string): boolean {
return Boolean(
readDecodedAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src"),
);
}
// Asset references inside CSS `url(...)`/`url("...")`/`url('...')` functions.
// Returns the inner path without quotes; comments are stripped first so
// `/* url(foo) */` is ignored. Bare `url()` and `data:` are excluded by the
// rules that consume this — the helper just yields raw URL values.
function extractCssUrlReferences(css: string): string[] {
const out: string[] = [];
const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
const urlPattern = /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g;
let m: RegExpExecArray | null;
while ((m = urlPattern.exec(noComments)) !== null) {
const raw = (m[2] ?? "").trim();
if (raw) out.push(raw);
}
return out;
}
// Top-level CSS selectors (comma-split) in a stylesheet, skipping at-rule headers
// (@media/@keyframes/...) and keyframe stops. Heuristic — the lint layer has no
// full CSS parser, and rules elsewhere in this file scan CSS the same way.
function extractCssSelectors(css: string): string[] {
const out: string[] = [];
const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
const ruleHeader = /([^{}]+)\{/g;
let m: RegExpExecArray | null;
while ((m = ruleHeader.exec(noComments)) !== null) {
const header = (m[1] ?? "").trim();
if (!header || header.startsWith("@")) continue;
for (const sel of header.split(",")) {
const s = sel.trim();
if (s) out.push(s);
}
}
return out;
}
// Class tokens in a selector's leftmost compound (before the first descendant /
// child / sibling combinator). `.frame .title` → ["frame"]; `.a.b > .c` → ["a","b"].
function leftmostCompoundClasses(selector: string): string[] {
const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
return (leftmost.match(/\.([\w-]+)/g) ?? []).map((c) => c.slice(1));
}
// Id token in a selector's leftmost compound. `#hero .title` → "hero";
// `.a#b > .c` → "b"; `.a .b` → null. Companion to leftmostCompoundClasses;
// splits on the same combinator set so the two agree on where "leftmost" ends.
function leftmostCompoundId(selector: string): string | null {
const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
return leftmost.match(/#([\w-]+)/)?.[1] ?? null;
}
// Class tokens + ids whose rule body sets a "heavy overlay" property
// (filter:blur, clip-path non-none, or radial-gradient). Only top-level rules
// are scanned — the flat `[^{}]*` body class naturally skips @keyframes
// bodies (which contain nested `{...}` stops) and other @-rules, so keyframe
// selectors like `0%`/`100%` don't leak in.
// fallow-ignore-next-line complexity
function collectHeavyOverlayHooks(styles: ExtractedBlock[]): {
classes: Set<string>;
ids: Set<string>;
} {
const classes = new Set<string>();
const ids = new Set<string>();
for (const style of styles) {
const noComments = style.content.replace(/\/\*[\s\S]*?\*\//g, "");
const ruleWithBody = /([^{}]+)\{([^{}]*)\}/g;
let m: RegExpExecArray | null;
while ((m = ruleWithBody.exec(noComments)) !== null) {
const header = (m[1] ?? "").trim();
const body = m[2] ?? "";
if (!header || header.startsWith("@")) continue;
if (!HEAVY_OVERLAY_CSS_PATTERN.test(body)) continue;
for (const sel of header.split(",")) {
const trimmed = sel.trim();
if (!trimmed) continue;
for (const cls of leftmostCompoundClasses(trimmed)) classes.add(cls);
const idToken = leftmostCompoundId(trimmed);
if (idToken) ids.add(idToken);
}
}
}
return { classes, ids };
}
// Distinct selectors across all <style> blocks whose leftmost compound keys off one
// of the root element's own classes — the ones that break under id-scoping.
function rootClassStyledSelectors(styles: ExtractedBlock[], rootClasses: string[]): string[] {
const offenders: string[] = [];
for (const style of styles) {
for (const selector of extractCssSelectors(style.content)) {
const hitsRoot = leftmostCompoundClasses(selector).some((c) => rootClasses.includes(c));
if (hitsRoot && !offenders.includes(selector)) offenders.push(selector);
}
}
return offenders;
}
// A `zoom` declaration and its value. The lookbehind keeps custom properties
// out: `--panel-zoom: 2` and `--zoom: 0.5` are author variables, not the CSS
// `zoom` property, and a plain \b would flag both.
const ZOOM_DECLARATION = /(?<![\w-])zoom\s*:\s*([^;}]+)/gi;
/** zoom values that leave the canvas alone; anything else rescales it. */
function isIdentityZoom(rawValue: string): boolean {
const value = rawValue
.trim()
.replace(/!\s*important\s*$/i, "")
.trim()
.toLowerCase();
return (
value === "" ||
value === "normal" ||
value === "unset" ||
value === "initial" ||
value === "revert" ||
value === "1" ||
value === "1.0" ||
value === "100%"
);
}
/** First rescaling `zoom` value in a declaration block, or null. */
function firstRescalingZoom(css: string): string | null {
ZOOM_DECLARATION.lastIndex = 0;
let match: RegExpExecArray | null;
while ((match = ZOOM_DECLARATION.exec(css)) !== null) {
const value = (match[1] ?? "").trim();
if (!isIdentityZoom(value)) return value.replace(/!\s*important\s*$/i, "").trim();
}
return null;
}
/**
* Does this selector's leftmost compound target the canvas itself — the
* composition root, or an ancestor of it? A zoom on a DESCENDANT is ordinary
* authoring and renders exactly as authored; only the canvas-level one
* desynchronises painted content from the declared frame.
*/
function targetsCanvasRoot(
selector: string,
rootId: string | null,
rootClasses: string[],
): boolean {
const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
const bare = leftmost.toLowerCase();
if (bare === "html" || bare === "body" || bare === ":root" || bare === "*") return true;
if (rootId && leftmostCompoundId(selector) === rootId) return true;
return leftmostCompoundClasses(selector).some((cls) => rootClasses.includes(cls));
}
/**
* A rescaling canvas-level `zoom`, with where it was declared. Collected in
* priority order — inline on the root, then <html>, then <body>, then
* stylesheet rules — because the rule reports the FIRST one it finds.
*
* `truncateSnippet` returns undefined for an empty normalised input, and
* `Finding.snippet` is optional for exactly that reason: an absent snippet is
* absent, not "". This mirrors that contract rather than coercing it away.
*/
type CanvasZoomHit = { where: string; value: string; snippet: string | undefined };
function inlineCanvasZoomHits(rootTag: OpenTag, tags: OpenTag[]): CanvasZoomHit[] {
const hits: CanvasZoomHit[] = [];
const htmlTag = findHtmlTag(tags);
const bodyTag = tags.find((tag) => tag.name.toLowerCase() === "body");
for (const [label, tag] of [
["the root element's inline style", rootTag],
["<html>'s inline style", htmlTag],
["<body>'s inline style", bodyTag],
] as const) {
if (!tag) continue;
const inline = readAttr(tag.raw, "style");
const value = inline ? firstRescalingZoom(inline) : null;
if (value) hits.push({ where: label, value, snippet: truncateSnippet(tag.raw) });
}
return hits;
}
/**
* The first selector in a comma list that targets the canvas, or null. Only the
* first matters: the rest of the list describes the same declaration block, so
* one hit per RULE is what the caller wants.
*/
function firstCanvasSelector(
header: string,
rootId: string | null,
rootClasses: string[],
): string | null {
for (const selector of header.split(",")) {
const trimmed = selector.trim();
if (trimmed && targetsCanvasRoot(trimmed, rootId, rootClasses)) return trimmed;
}
return null;
}
/** A canvas-level rescaling `zoom` declared by one CSS rule, or null. */
function canvasZoomInRule(
header: string,
body: string,
rootId: string | null,
rootClasses: string[],
): CanvasZoomHit | null {
const trimmedHeader = header.trim();
// An at-rule's "header" is `@media ...`, not a selector list.
if (!trimmedHeader || trimmedHeader.startsWith("@")) return null;
const value = firstRescalingZoom(body);
if (!value) return null;
const selector = firstCanvasSelector(trimmedHeader, rootId, rootClasses);
if (!selector) return null;
return {
where: `\`${selector}\``,
value,
snippet: truncateSnippet(`${selector} { zoom: ${value} }`),
};
}
function stylesheetCanvasZoomHits(
styles: ExtractedBlock[],
rootId: string | null,
rootClasses: string[],
): CanvasZoomHit[] {
const hits: CanvasZoomHit[] = [];
for (const style of styles) {
const ruleWithBody = /([^{}]+)\{([^{}]*)\}/g;
let match: RegExpExecArray | null;
while ((match = ruleWithBody.exec(stripCssComments(style.content))) !== null) {
const hit = canvasZoomInRule(match[1] ?? "", match[2] ?? "", rootId, rootClasses);
if (hit) hits.push(hit);
}
}
return hits;
}
function canvasZoomHits(
rootTag: OpenTag,
tags: OpenTag[],
styles: ExtractedBlock[],
rootId: string | null,
rootClasses: string[],
): CanvasZoomHit[] {
return [
...inlineCanvasZoomHits(rootTag, tags),
...stylesheetCanvasZoomHits(styles, rootId, rootClasses),
];
}
/** Declared variable ids from an <html> tag's raw text; null when the JSON is unparseable. */
function collectDeclaredVariableIds(htmlTagRaw: string): Set<string> | null {
const declared = new Set<string>();
const raw = readJsonAttr(htmlTagRaw, "data-composition-variables");
if (!raw) return declared;
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
return null;
}
if (!Array.isArray(parsed)) return declared;
for (const entry of parsed) {
const id = (entry as { id?: unknown } | null)?.id;
if (typeof id === "string") declared.add(id);
}
return declared;
}
/**
* Union declared variable ids from every element carrying
* `data-composition-variables`: full-document comps hold it on `<html>`;
* template/fragment sub-comps hold it on their composition root div. Returns
* null if any occurrence has unparseable JSON.
*/
// fallow-ignore-next-line complexity
function variablesDeclarationFindings(
tag: OpenTag,
tags: readonly OpenTag[],
): HyperframeLintFinding[] {
const raw = readJsonAttr(tag.raw, "data-composition-variables");
if (!raw) return [];
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch (err) {
const reason = err instanceof Error ? err.message : "unknown";
return [
{
code: "invalid_composition_variables_declaration",
severity: "error",
message: `data-composition-variables is not valid JSON (${reason}).`,
fixHint:
'Provide a JSON array of variable declarations: data-composition-variables=\'[{"id":"title","type":"string","label":"Title","default":"Hello"}]\'.',
snippet: truncateSnippet(tag.raw),
},
];
}
if (!Array.isArray(parsed)) {
return [
{
code: "invalid_composition_variables_declaration",
severity: "error",
message: "data-composition-variables must be a JSON array of variable declarations.",
fixHint:
'Wrap declarations in [] and give each an id, type, label, and default: \'[{"id":"title","type":"string","label":"Title","default":"Hello"}]\'.',
snippet: truncateSnippet(tag.raw),
},
];
}
const findings: HyperframeLintFinding[] = [];
const knownTypes = new Set<string>(COMPOSITION_VARIABLE_TYPES);
// Ids whose value the runtime pushes through isSafeMediaUrl: every
// data-var-src binding, plus image-typed variables (always consumed as a
// URL even when the binding lives in a sub-composition this file can't see).
const varSrcIds = new Set<string>();
for (const other of tags) {
const bound = readAttr(other.raw, "data-var-src");
if (bound) varSrcIds.add(bound);
}
for (let i = 0; i < parsed.length; i += 1) {
const entry = parsed[i];
if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
findings.push({
code: "invalid_composition_variables_declaration",
severity: "error",
message: `data-composition-variables entry [${i}] must be an object with id, type, label, and default.`,
snippet: truncateSnippet(tag.raw),
});
continue;
}
const e = entry as Record<string, unknown>;
const missing: string[] = [];
if (typeof e.id !== "string") missing.push("id");
if (typeof e.type !== "string" || !knownTypes.has(e.type)) missing.push("type");
if (typeof e.label !== "string") missing.push("label");
if (!("default" in e)) missing.push("default");
if (missing.length > 0) {
findings.push({
code: "invalid_composition_variables_declaration",
severity: "error",
message: `data-composition-variables entry [${i}] is missing or has invalid: ${missing.join(", ")}. Type must be one of string, number, color, boolean, enum, font, image.`,
snippet: truncateSnippet(tag.raw),
});
continue;
}
const id = String(e.id);
if (
(e.type === "image" || varSrcIds.has(id)) &&
typeof e.default === "string" &&
e.default.length > 0 &&
!isSafeMediaUrl(e.default)
) {
findings.push({
code: "unloadable_media_variable_default",
severity: "error",
message: `Variable "${id}" defaults to a URL the runtime will refuse to load, so any element bound to it renders its authored fallback src instead and the render still exits 0.`,
fixHint: `Media URLs must be relative, http(s), blob:, or a data:image/* URI. Copy the file into the project and reference it relatively (e.g. "assets/bg.png") rather than by absolute path.`,
snippet: truncateSnippet(tag.raw),
});
}
}
return findings;
}
export function collectAllDeclaredVariableIds(tags: readonly OpenTag[]): Set<string> | null {
const all = new Set<string>();
for (const tag of tags) {
if (!readAttr(tag.raw, "data-composition-variables")) continue;
const ids = collectDeclaredVariableIds(tag.raw);
if (ids === null) return null;
for (const id of ids) all.add(id);
}
return all;
}
/**
* Declared ids to validate `data-var-*` bindings against, or null to skip the
* file: unparseable declarations (reported elsewhere), or a fragment with no
* `<html>` and no declarations of its own (its values come from a host's
* data-variable-values, which this file can't see).
*/
function declaredIdsForBindingCheck(tags: readonly OpenTag[]): Set<string> | null {
const declared = collectAllDeclaredVariableIds(tags);
if (declared === null) return null;
if (declared.size === 0 && !findHtmlTag(tags)) return null;
return declared;
}
function isInsideInertTemplate(tag: OpenTag, tags: readonly OpenTag[]): boolean {
return tags.some(
(candidate) =>
candidate.name === "template" &&
candidate.closeIndex != null &&
tag.index > candidate.index &&
tag.index < candidate.closeIndex,
);
}
// `(?<![\w-])` not `\b`: the hyphen in a custom property is a word break, so a
// plain boundary matches `--z-index: -1` and `--panel-z-index: -1`, which
// declare variables and stack nothing. `-0` is excluded because it is not a
// negative stacking level; `-01` and `-0.5` are.
const NEGATIVE_Z_INDEX = /(?<![\w-])z-index\s*:\s*-(?!0(?:\s*[;}]|\s*$))([\d.]+)/g;
// Name the selector that owns the declaration so the finding points at
// something the author can search for.
function cssOwnerSelector(content: string, matchIndex: number): string | undefined {
const blockStart = content.lastIndexOf("{", matchIndex);
if (blockStart === -1) return undefined;
const previousBlockEnd = content.lastIndexOf("}", blockStart);
const lines = content
.slice(previousBlockEnd + 1, blockStart)
.trim()
.split("\n");
return lines[lines.length - 1]?.trim() || undefined;
}
function elementSelector(tag: OpenTag): string | undefined {
const elementId = readAttr(tag.raw, "id");
return elementId ? `#${elementId}` : undefined;
}
function negativeZIndexFinding(
match: RegExpExecArray,
selector: string | undefined,
): HyperframeLintFinding {
const level = match[1] ?? "";
return {
code: "negative_z_index",
severity: "warning",
...(selector ? { selector } : {}),
message:
`\`z-index: -${level}\` paints the element behind its nearest stacking context's own content. ` +
"With no stacking-context ancestor that context is the composition root itself, so an opaque " +
"background there hides it entirely: in the DOM, laid out, and absent from the picture. " +
"A transparent root leaves it visible. Siblings at `z-index: 0` or above are unaffected.",
fixHint:
"Give the element's parent a stacking context - `isolation: isolate` is the cheapest, and " +
"`transform`, `filter`, `opacity` below 1, `contain: paint` and `will-change` all work too. " +
"The negative-z child then paints above that parent's background and renders normally. " +
"Or express paint order through DOM order - an earlier sibling paints behind a " +
"later one - and raise the elements that should sit in front rather than lowering this one.",
snippet: truncateSnippet(match[0]),
};
}
export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
// duplicate_composition_id catches meta-tag/root collisions that create duplicate composition entries.
({ tags }) => {
const tagsByCompositionId = new Map<string, string[]>();
for (const tag of tags) {
if (isInsideInertTemplate(tag, tags)) continue;
// A `data-composition-src` element is a MOUNT of a sub-composition, not a
// composition root, and sub-compositions.md documents mounting one source
// repeatedly with different `data-variable-values` to get per-instance
// variations. Those mounts legitimately share an id: the runtime rewrites
// repeated ones to `id__hf1`, `id__hf2` so they coexist. Counting them
// here made the documented pattern an error with no correct way to
// satisfy it. The collision this rule exists for -- a <meta> tag carrying
// the root's id, per its own fixHint -- is unaffected, since that tag has
// no `data-composition-src`.
if (readAttr(tag.raw, "data-composition-src")) continue;
const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
if (!compositionId || compositionId.trim().length === 0) continue;
const matchingTags = tagsByCompositionId.get(compositionId) ?? [];
matchingTags.push(tag.raw);
tagsByCompositionId.set(compositionId, matchingTags);
}
const findings: HyperframeLintFinding[] = [];
for (const [compositionId, matchingTags] of tagsByCompositionId) {
if (matchingTags.length < 2) continue;
findings.push({
code: "duplicate_composition_id",
severity: "error",
message: `Composition id "${compositionId}" is used by ${matchingTags.length} elements. Each data-composition-id value must be unique within a composition file.`,
fixHint:
"Keep data-composition-id on exactly one element, the composition root. Remove it from metadata or duplicate hosts, especially a <meta> tag carrying the same data-composition-id as the root <div>, which causes a silent duplicate-id collision.",
snippet: truncateSnippet(matchingTags[0] ?? ""),
});
}
return findings;
},
// invalid_parent_traversal_in_asset_path — catches `../` traversal in src,
// href, inline-style url(), and <style> url() asset references on
// compositions. Sub-compositions live under compositions/ but are served
// with the project root as their base URL, so any `../`-traversing path
// climbs above the project root and 404s in Studio preview. Renders
// tolerate it because the server-side bundler rewrites `../foo` against
// each sub-composition's source path; the runtime now mirrors that fallback
// (see rewriteSubCompositionAssetPaths in runtime/compositionLoader.ts), but
// the authoring-time signal is still wrong — flag it at lint time so the
// baked path is plain root-relative and matches what the bundler emits.
//
// Mirrors the runtime fallback's surface: `[src]` / `[href]` attribute
// values, `[style]` inline url(), and `<style>` block url() references.
// Skips absolute URLs (http(s)://, //, data:, /-prefixed root-relative),
// hash anchors, and plain relative paths (`assets/x.mp4`) — only `../`
// traversal is flagged. Subsumes the older `../capture/`-specific rule.
// fallow-ignore-next-line complexity
({ tags, styles, rawSource, options }) => {
if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
const offenders: string[] = [];
const collect = (value: string | null) => {
if (!value) return;
const trimmed = value.trim();
if (!trimmed.startsWith("../") && trimmed !== "..") return;
offenders.push(trimmed);
};
for (const tag of tags) {
collect(readAttr(tag.raw, "src"));
collect(readAttr(tag.raw, "href"));
// Use readJsonAttr for `style` — inline url('...') values contain the
// opposite quote, which readAttr's [^"']+ class would truncate.
const styleAttr = readJsonAttr(tag.raw, "style");
if (styleAttr) {
for (const url of extractCssUrlReferences(styleAttr)) collect(url);
}
}
for (const style of styles) {
for (const url of extractCssUrlReferences(style.content)) collect(url);
}
if (offenders.length === 0) return [];
// Group counts by leading path token (e.g. ../capture/, ../assets/, ../../assets/)
// so the message names the offending prefixes instead of a bare count.
const prefixCounts = new Map<string, number>();
for (const path of offenders) {
const prefix = path.match(/^(?:\.\.\/)+[^/]+\//)?.[0] ?? path;
prefixCounts.set(prefix, (prefixCounts.get(prefix) ?? 0) + 1);
}
const prefixSummary = Array.from(prefixCounts.entries())
.sort(([, a], [, b]) => b - a)
.map(([prefix, count]) => (count > 1 ? `${prefix} (${count})` : prefix))
.join(", ");
return [
{
code: "invalid_parent_traversal_in_asset_path",
severity: "error",
message:
`Found ${offenders.length} asset path(s) traversing above the project root with "../" ` +
`(${prefixSummary}). Renders rewrite this against each sub-composition's source path, but Studio preview and other live consumers resolve against the project root and 404.`,
fixHint:
'Use plain root-relative paths (e.g. "assets/...", "capture/...", "fonts/...") — compositions are served with the project root as their base URL, so paths must be root-relative, not relative to the compositions/ directory.',
},
];
},
// composition_file_too_large
({ rawSource, options }) => {
if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
const lineCount = countStructuralLines(rawSource);
if (lineCount <= MAX_COMPOSITION_LINES) return [];
const splitTarget = options.isSubComposition
? "Split this sub-composition further into smaller .html files"
: "Split coherent scenes or layers into separate .html files under compositions/";
return [
{
code: "composition_file_too_large",
severity: "warning",
message: `This HTML composition file has ${lineCount} lines. Smaller sub-compositions are easier to read, iterate on, and diff.`,
fixHint: `${splitTarget}, then mount them from the parent with data-composition-src so each file stays small enough to inspect, revise, and validate independently.`,
},
];
},
// timeline_track_too_dense
// fallow-ignore-next-line complexity
({ tags, options }) => {
const trackCounts = new Map<string, number>();
for (const tag of tags) {
if (TRACK_DENSITY_EXEMPT_TAGS.has(tag.name)) continue;
if (isCaptionCue(tag)) continue;
if (isCompositionRootOrMount(tag.raw)) continue;
if (!readAttr(tag.raw, "data-start")) continue;
const track = readAttr(tag.raw, COMPOSITION_ATTRIBUTES.trackIndex);
if (!track) continue;
trackCounts.set(track, (trackCounts.get(track) ?? 0) + 1);
}
const findings: HyperframeLintFinding[] = [];
for (const [track, count] of trackCounts) {
if (count <= MAX_TIMED_ELEMENTS_PER_TRACK) continue;
const splitTarget = options.isSubComposition
? "Move coherent scene groups into smaller .html files"
: "Move coherent scene groups into separate .html files under compositions/";
findings.push({
code: "timeline_track_too_dense",
severity: "warning",
message: `Track ${track} has ${count} timed elements in this HTML file. Smaller sub-compositions keep timelines easier to read, iterate on, and diff.`,
fixHint: `${splitTarget} and mount them from the parent with data-composition-src so the timeline stays easier to inspect, revise, and validate.`,
});
}
return findings;
},
// deprecated_data_layer + deprecated_data_end
// fallow-ignore-next-line complexity
({ tags }) => {
const findings: HyperframeLintFinding[] = [];
for (const tag of tags) {
const timing = readTagTiming(tag.raw);
if (timing.diagnostics.some(({ code }) => code === "deprecated-layer")) {
const elementId = readAttr(tag.raw, "id") || undefined;
findings.push({
code: "deprecated_data_layer",
severity: "error",
message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-layer instead of data-track-index.`,
elementId,
fixHint:
"Replace data-layer with data-track-index, which is the canonical name Studio and the linter read. Neither name is read by the render.",
snippet: truncateSnippet(tag.raw),
});
}
if (timing.diagnostics.some(({ code }) => code === "deprecated-end")) {
const elementId = readAttr(tag.raw, "id") || undefined;
const conflicting = timing.diagnostics.some(({ code }) => code === "conflicting-end");
// Two shapes reach here after the false-positive fix (see
// compositionContract.ts `diagnoseDerivedEnd`): the truly-legacy shape
// (no data-duration, data-end alone) and the stale-companion shape
// (data-duration present but paired with a data-end that disagrees).
// A consistent data-duration + data-end pair — the shape the compiler
// emits — is silent and never reaches this branch.
const message = conflicting
? `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-end that disagrees with data-duration. Remove the stale data-end; the compiler regenerates it from data-duration.`
: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`;
findings.push({
code: "deprecated_data_end",
severity: "error",
message,
elementId,
fixHint:
"Replace data-end with data-duration. The compiler generates data-end from data-duration automatically.",
snippet: truncateSnippet(tag.raw),
});
}
}
return findings;
},
// split_data_attribute_selector
({ scripts, styles }) => {
const findings: HyperframeLintFinding[] = [];
const splitDataAttrSelectorPattern =
/\[data-composition-id=(["'])([^"'\]]+)\1\s+(data-[\w:-]+)=(["'])([^"'\]]*)\4\]/g;
const scan = (content: string) => {
splitDataAttrSelectorPattern.lastIndex = 0;
let match: RegExpExecArray | null;
while ((match = splitDataAttrSelectorPattern.exec(content)) !== null) {
const compId = match[2] ?? "";
const attrName = match[3] ?? "";
const attrValue = match[5] ?? "";
findings.push({
code: "split_data_attribute_selector",
severity: "error",
message:
`Selector "${match[0]}" combines two attributes inside one CSS attribute selector. ` +
"Browsers reject it, so GSAP timelines or querySelector calls will fail before registering.",
selector: match[0],
fixHint: `Use separate attribute selectors: [data-composition-id="${compId}"][${attrName}="${attrValue}"].`,
snippet: truncateSnippet(match[0]),
});
}
};
for (const style of styles) scan(stripCssComments(style.content));
for (const script of scripts) scan(stripJsComments(script.content));
return findings;
},
// template_literal_selector
({ scripts }) => {
const findings: HyperframeLintFinding[] = [];
for (const script of scripts) {
const templateLiteralSelectorPattern =
/(?:querySelector|querySelectorAll)\s*\(\s*`[^`]*\$\{[^}]+\}[^`]*`\s*\)/g;
const scanned = stripJsCode(script.content);
let tlMatch: RegExpExecArray | null;
while ((tlMatch = templateLiteralSelectorPattern.exec(scanned)) !== null) {
findings.push({
code: "template_literal_selector",
severity: "error",
message:
"querySelector uses a template literal variable (e.g. `${compId}`). " +
"The HTML bundler's CSS parser crashes on these. Use a hardcoded string instead.",
fixHint:
"Replace the template literal variable with a hardcoded string. The bundler's CSS parser cannot handle interpolated variables in script content.",
snippet: truncateSnippet(
script.content.slice(tlMatch.index, tlMatch.index + tlMatch[0].length),
),
});
}
}
return findings;
},
// timed_element_missing_clip_class
// fallow-ignore-next-line complexity
({ tags }) => {
const findings: HyperframeLintFinding[] = [];
// `img` sits here for the same reason `video` and `audio` already did: the
// three media primitives are authored without `class="clip"` in the
// canonical clip block (packages/core/docs/core.md), so requiring it on the
// `<img>` alone errored on the documented pattern while its two siblings on
// the adjacent lines passed.
const skipTags = new Set(["audio", "img", "video", "script", "style", "template"]);
for (const tag of tags) {
if (skipTags.has(tag.name)) continue;
// Skip composition hosts
if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
if (readAttr(tag.raw, "data-composition-src")) continue;
const hasStart = readAttr(tag.raw, "data-start") !== null;
const hasDuration = readAttr(tag.raw, "data-duration") !== null;
// data-track-index alone marks a layer container, not a time-bounded clip
if (!hasStart && !hasDuration) continue;
const classAttr = readAttr(tag.raw, "class") || "";
const hasClip = classAttr.split(/\s+/).includes("clip");
if (hasClip) continue;
const elementId = readAttr(tag.raw, "id") || undefined;
findings.push({
code: "timed_element_missing_clip_class",
// Not an error: the runtime drives timed visibility off the `data-start`
// ATTRIBUTE, not this class — `syncTimedElementVisibility` walks
// `querySelectorAll("[data-start]")` and toggles `style.visibility`
// regardless of class (pinned by the runtime's own init test, which
// uses a bare `<div data-start data-duration>` with no `class="clip"`).
// The class is an authoring convention the tooling reads, so a missing
// one is worth flagging but does not break the render.
severity: "warning",
message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has timing attributes but no class="clip". The runtime still hides it outside its time range, but Studio and the GSAP clip-ownership rules use .clip to recognise a clip, so leaving it off makes the element harder to edit and to lint.`,
elementId,
fixHint:
'Add class="clip" to the element so Studio and the linter can recognise it as a clip.',
snippet: truncateSnippet(tag.raw),
});
}
return findings;
},
// standalone_composition_wrapped_in_template
({ rawSource, options }) => {
const findings: HyperframeLintFinding[] = [];
if (options.isSubComposition) return findings;
const trimmed = rawSource.trimStart().toLowerCase();
if (trimmed.startsWith("<template")) {
findings.push({
code: "standalone_composition_wrapped_in_template",
severity: "error",
message:
"Root index.html is wrapped in a <template> tag. " +
"Only sub-compositions loaded via data-composition-src should use <template> wrappers. " +
"The runtime cannot play a standalone composition inside a template.",
fixHint:
"Remove the <template> wrapper. Use <!DOCTYPE html><html>...<div data-composition-id>...</div>...</html> instead.",
});
}
return findings;
},
// root_composition_missing_html_wrapper
({ rawSource, rootTag, options }) => {
const findings: HyperframeLintFinding[] = [];
if (options.isSubComposition) return findings;
const trimmed = rawSource.trimStart().toLowerCase();
// Compositions inside <template> are caught by standalone_composition_wrapped_in_template
if (trimmed.startsWith("<template")) return findings;
const hasDoctype = trimmed.startsWith("<!doctype") || trimmed.startsWith("<html");
const hasComposition = rawSource.includes("data-composition-id");
if (hasComposition && !hasDoctype) {
findings.push({
code: "root_composition_missing_html_wrapper",
severity: "error",
message:
"Composition starts with a bare element instead of a proper HTML document. " +
"An index.html that contains data-composition-id but no <!DOCTYPE html>, <html>, or <body> " +
"is a fragment — browsers quirks-mode it, the preview server cannot load it, and " +
"the bundler will fail to inject runtime scripts.",
fixHint:
'Wrap the composition in <!DOCTYPE html><html><head><meta charset="UTF-8"></head><body>...</body></html>.',
snippet: rootTag ? truncateSnippet(rootTag.raw) : undefined,
});
}
return findings;
},
// missing_data_no_timeline
// The producer polls window.__timelines[id] with a 45-second timeout waiting
// for GSAP timeline registration. Compositions that never call
// window.__timelines[id] = tl stall for 45 s every render. Adding
// data-no-timeline to the root element tells the producer to skip the poll.
({ rootTag, rootCompositionId, scripts, rawSource, options }) => {
if (options.isSubComposition) return [];
if (!rootCompositionId || !rootTag) return [];
// readAttr only matches valued attrs (attr="..."); data-no-timeline is
// typically boolean (no value). Strip quoted attribute values first to
// avoid matching attr names that appear inside other values
// (e.g. title="add data-no-timeline here"), then check with a boundary
// that rejects hyphenated variants (data-no-timeline-start has '-' next,
// not a word-break char).
const tagNoValues = rootTag.raw.replace(/"[^"]*"|'[^']*'/g, '""');
if (/(?:^|\s)data-no-timeline(?=[\s>=/]|$)/i.test(tagNoValues)) return [];
// Can't scan external script files for timeline registration; skip to avoid
// false positives on compositions that register via a bundled JS file.
if (/<script\b[^>]*\bsrc\s*=/i.test(rawSource)) return [];
const registersTimeline = scripts.some((s) => s.content.includes("window.__timelines["));
if (registersTimeline) return [];
return [
{
code: "missing_data_no_timeline",
severity: "warning",
message:
"This composition has no `window.__timelines` registration but is missing `data-no-timeline`. " +
"The producer polls for timeline registration for up to 45 seconds before timing out, " +
"adding 45 s to every render.",
fixHint:
'Add `data-no-timeline` to the root element to skip the poll: `<div data-composition-id="..." data-no-timeline ...>`.',
snippet: truncateSnippet(rootTag.raw),
},
];
},
// negative_z_index
// An element at a negative z-index is silently absent from both `snapshot`
// and `render`, while siblings differing only in the sign of z-index render
// exactly (heygen-com/hyperframes#4366). lint, validate and render all exit 0
// and report nothing, so the first suspicion falls on the author's own CSS.
// NOT A RENDERER DEFECT -- ORDINARY CSS PAINTING ORDER, measured at 0.8.72.
// The element is PAINTED; it is simply painted beneath something opaque. Remove
// every opaque background above it and the same `z-index: -1` band renders at
// full coverage, identically to the same band with `z-index` deleted. A negative-z
// descendant paints at step 2 of its nearest stacking context -- above that
// context root's own background, but below the context's positioned in-flow
// content -- so a `position: relative` composition root with an opaque background
// paints over it. That is the shape #4366 reports; nothing is dropped and the
// renderer has no say in it.
//
// Kept as a warning because authors hit it and nothing explains why: the element
// is in the DOM, laid out, and invisible. The message therefore names the CAUSE
// and the remedy rather than implying the tool failed.
//
// THE CONDITION IS LOAD-BEARING AND THE MESSAGE STATES IT. The element is only
// dropped when its nearest ancestor stacking context is the composition root,
// which is the shape #4366 reports. Give any ancestor a stacking context and it
// renders correctly: measured at 0.8.72 on ONE frame carrying the same
// `z-index: -1` band under six triggers -- isolation:isolate, transform,
// opacity below 1, filter, contain:paint, will-change -- all six PRESENT at full
// coverage, against the no-stacking-context control ABSENT at zero coverage.
// That is ordinary CSS painting order: a negative-z child paints above its
// stacking context root's own background, so only the root case is hidden.
//
// This rule matches CSS TEXT and does not resolve the cascade, so it cannot know
// whether an ancestor forms a stacking context and fires on both shapes. That is
// why the message is CONDITIONAL rather than an assertion of absence: an
// unconditional "silently dropped" is false for every isolated case, and a lint
// message that overclaims is how authors learn to disregard the rule.
({ tags, styles }) => {
const findings: HyperframeLintFinding[] = [];
for (const style of styles) {
const content = stripCssComments(style.content);
NEGATIVE_Z_INDEX.lastIndex = 0;
let match: RegExpExecArray | null;
while ((match = NEGATIVE_Z_INDEX.exec(content)) !== null) {
findings.push(negativeZIndexFinding(match, cssOwnerSelector(content, match.index)));
}
}
for (const tag of tags) {
const inline = readAttr(tag.raw, "style");
if (!inline) continue;
NEGATIVE_Z_INDEX.lastIndex = 0;
const match = NEGATIVE_Z_INDEX.exec(inline);
if (match) findings.push(negativeZIndexFinding(match, elementSelector(tag)));
}
return findings;
},
// requestanimationframe_in_composition
({ scripts, rawSource, options }) => {
if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
const findings: HyperframeLintFinding[] = [];
for (const script of scripts) {
const stripped = stripJsCode(script.content);
if (/requestAnimationFrame\s*\(/.test(stripped)) {
findings.push({
code: "requestanimationframe_in_composition",
severity: "error",
message:
"`requestAnimationFrame` runs on wall-clock time, not the GSAP timeline. It will not sync with frame capture and may cause flickering or missed frames during rendering.",
fixHint:
"Use GSAP tweens or onUpdate callbacks instead of requestAnimationFrame for animation logic.",
snippet: truncateSnippet(script.content),
});
}
}
return findings;
},
// invalid_variable_values_json
// Host elements (`[data-composition-src]`) carry per-instance values via
// `data-variable-values`. The runtime swallows JSON errors silently and
// falls back to declared defaults, which masks typos. This rule surfaces
// the parse failure so authors notice before render time.
// fallow-ignore-next-line complexity
({ tags }) => {
const findings: HyperframeLintFinding[] = [];
for (const tag of tags) {
const raw = readJsonAttr(tag.raw, "data-variable-values");
if (!raw) continue;
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch (err) {
const reason = err instanceof Error ? err.message : "unknown";
findings.push({
code: "invalid_variable_values_json",
severity: "error",
message: `data-variable-values is not valid JSON (${reason}).`,
fixHint:
'Wrap the attribute value in single quotes and the JSON keys/values in double quotes, e.g. data-variable-values=\'{"title":"Hello"}\'.',
elementId: readAttr(tag.raw, "id") || undefined,
snippet: truncateSnippet(tag.raw),
});
continue;
}
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
findings.push({
code: "invalid_variable_values_json",
severity: "error",
message:
'data-variable-values must be a JSON object keyed by variable id (e.g. {"title":"Hello"}).',
fixHint:
"Replace the value with a JSON object whose keys are variable ids declared in the sub-composition's data-composition-variables.",
elementId: readAttr(tag.raw, "id") || undefined,
snippet: truncateSnippet(tag.raw),
});
}
}
return findings;
},
// unknown_variable_binding
// data-var-src / data-var-text bind an element to a declared variable id;
// the runtime silently keeps the authored fallback when the id resolves to
// nothing, so a typo'd binding is invisible until a customer's override
// does nothing. Skipped for fragment files (no <html>): their values come
// from a host's data-variable-values, which this file can't see.
({ tags }) => {
// Declarations live on <html> (full-document comps) OR the composition root
// div (template/fragment sub-comps); declaredIdsForBindingCheck unions both
// and returns null for files this rule should skip.
const declared = declaredIdsForBindingCheck(tags);
if (!declared) return [];
const findings: HyperframeLintFinding[] = [];
for (const tag of tags) {
for (const attr of ["data-var-src", "data-var-text"]) {
const id = readAttr(tag.raw, attr)?.trim();
if (!id || declared.has(id)) continue;
findings.push({
code: "unknown_variable_binding",
severity: "warning",
message: `<${tag.name}> binds ${attr}="${id}" but no variable "${id}" is declared in data-composition-variables — the binding will silently keep the authored fallback.`,
fixHint: `Declare the variable on the composition root (<html>, or the [data-composition-id] root element for a template/fragment comp): data-composition-variables='[{"id":"${id}","type":"${attr === "data-var-src" ? "image" : "string"}","label":"${id}","default":"..."}]', or fix the binding id.`,
elementId: readAttr(tag.raw, "id") || undefined,
snippet: truncateSnippet(tag.raw),
});
}
}
return findings;
},
// invalid_composition_variables_declaration
// The runtime parses `data-composition-variables` and silently returns []
// on any structural problem. Surface JSON / shape failures so authors
// catch them at lint time rather than wondering why their `getVariables()`
// defaults aren't applied.
// Checked on every element that declares: <html>, or the composition root.
({ tags }) =>
tags
.filter((tag) => readJsonAttr(tag.raw, "data-composition-variables"))
.flatMap((tag) => variablesDeclarationFindings(tag, tags)),
// html_dir_attribute_breaks_render — valid non-LTR dir values on
// <html> renders correctly in preview/snapshot but produces a fully
// blank/black video from render, with no other lint/validate/inspect
// check catching it (output file size, far smaller than expected, is the
// only tell). Confirmed independently by two separate reports, both
// diagnosing the same exact trigger and the same fix: drop dir from
// <html>, keep lang, and scope `direction: rtl` to individual
// text-containing elements via CSS instead (text still bidi-shapes
// correctly). Advisory-only — this does not attempt to fix the render
// pipeline's own root cause (suspected to be a capture step that clips a
// fixed top-left-origin screenshot region, which RTL layout can shift the
// actual content away from), only surfaces the already-confirmed footgun
// before someone hits it blind.
({ tags }) => {
const htmlTag = findHtmlTag(tags);
if (!htmlTag) return [];
const dir = readAttr(htmlTag.raw, "dir");
if (!dir) return [];
const normalizedDir = dir.toLowerCase();
if (normalizedDir !== "rtl" && normalizedDir !== "auto") return [];
const scopedDirection = normalizedDir === "auto" ? 'dir="auto"' : `direction: ${normalizedDir}`;
return [
{
code: "html_dir_attribute_breaks_render",
severity: "error",
message: `<html dir="${dir}"> renders correctly in preview/snapshot but produces a fully blank/black video from render — a confirmed, silent failure.`,
fixHint: `Remove dir="${dir}" from <html>. Keep lang, and scope ${scopedDirection} to individual text-containing elements instead — text still shapes correctly via the browser's own bidi algorithm.`,
snippet: truncateSnippet(htmlTag.raw),
},
];
},
// subcomposition_blanks_before_host
// Warns when a full-bleed sub-composition slot ends before the host composition
// does, leaving the slot blank for the remainder (issue #1540). Scoped narrowly to
// the high-signal shape — a sole/dominant external mount starting at ~0 — so it
// stays silent on intentional short clips (an intro followed by other clips that
// carry the timeline forward).
// fallow-ignore-next-line complexity
({ tags, rootTag }) => {
if (!rootTag) return [];
const rootDuration = Number(readAttr(rootTag.raw, "data-duration"));
if (!Number.isFinite(rootDuration) || rootDuration <= 0) return [];
// Two independent knobs that happen to share a 0.5s magnitude. Tuned for
// real hosts (tens to hundreds of seconds); on a very short host (~6s) the
// EPSILON slack would let a ~10% blank tail pass unflagged — acceptable
// because the silent-blank trap this rule targets only matters at scale.
const EPSILON = 0.5; // seconds; tolerance for "ends/covers near the host end"
const START_TOLERANCE = 0.5; // seconds; "starts at the composition start"
const round3 = (n: number) => Math.round(n * 1000) / 1000;
// Timed children of the root. An element with data-start but no usable
// data-duration is treated as covering the tail (end = Infinity), so an
// unknown-length sibling suppresses the warning rather than triggering it.
const timed = tags
.filter((tag) => tag.index !== rootTag.index && readAttr(tag.raw, "data-start") !== null)
.map((tag) => {
const start = Number(readAttr(tag.raw, "data-start")) || 0;
const dur = Number(readAttr(tag.raw, "data-duration"));
const end = Number.isFinite(dur) && dur > 0 ? start + dur : Infinity;
return { tag, start, end };
});
// `tags` is a flat list (no nesting depth), so a timed element nested
// *inside* a candidate slot is treated as a tail-covering sibling rather
// than a descendant. Acceptable: external src mounts are empty by
// convention (content is loaded from the linked file), so the only
// false-negative path is rare and matches the flat-tag scope of the
// sibling rules in this file.
const tailCovered = (exceptIndex: number) =>
timed.some((t) => t.tag.index !== exceptIndex && t.end >= rootDuration - EPSILON);
const findings: HyperframeLintFinding[] = [];
for (const t of timed) {
if (readAttr(t.tag.raw, "data-composition-src") === null) continue; // external slot only
if (t.start > START_TOLERANCE) continue; // must start at the composition start
if (!Number.isFinite(t.end)) continue; // known, finite slot length
if (t.end >= rootDuration - EPSILON) continue; // already fills the host window
if (tailCovered(t.tag.index)) continue; // another clip covers the tail — not full-bleed
const elementId = readAttr(t.tag.raw, "id") || undefined;
const gap = round3(rootDuration - t.end);
findings.push({
code: "subcomposition_blanks_before_host",
severity: "warning",
message: `<${t.tag.name}${elementId ? ` id="${elementId}"` : ""}> sub-composition ends at ${round3(t.end)}s but the composition runs to ${round3(rootDuration)}s — its slot will be blank for ~${gap}s.`,
elementId,
fixHint: `data-duration is the slot's visible window. Set this sub-composition's data-duration to ${round3(rootDuration - t.start)} to fill the host window, or add another clip to cover the remaining ~${gap}s.`,
snippet: truncateSnippet(t.tag.raw),
});
}
return findings;
},
// subcomposition_root_styled_by_class
// A sub-composition's <style> is scoped at render time to
// `[data-composition-id="<id>"] <selector>` so scenes inlined into one document
// can't leak styles into each other. A rule whose LEFTMOST selector is the ROOT
// element's own class (e.g. `.frame { ... }` on the same element that carries
// data-composition-id) therefore becomes a DESCENDANT selector that can never
// match the SCOPED element itself. NOTE on the symptom: since #1886 the producer
// preserves the authored root as a `data-hf-inner-root` wrapper INSIDE the scoped
// element (regression fixture packages/producer/tests/sub-comp-class-selector),
// so the class still matches as a descendant and the scene no longer renders
// unstyled. This rule is now a consistency constraint, not a render-bug guard:
// `#root` is the shape the registry blocks model and the one the scoper
// special-cases. Style the root via `#root`
// (the scoper special-cases the root id) and descendants via plain selectors,
// like the registry blocks — the runtime already scopes each scene by id, so a
// class namespace on the root is redundant.
({ rootTag, rootCompositionId, styles, options }) => {
if (!options.isSubComposition) return [];
if (isRegistrySourceFile(options.filePath)) return [];
if (!rootTag || !rootCompositionId) return [];
const rootClasses = (readAttr(rootTag.raw, "class") || "").split(/\s+/).filter(Boolean);
if (rootClasses.length === 0) return [];
const offenders = rootClassStyledSelectors(styles, rootClasses);
if (offenders.length === 0) return [];
const example = offenders.slice(0, 3).join(", ");
return [
{
code: "subcomposition_root_styled_by_class",
severity: "error",
message:
`Root element has class="${rootClasses.join(" ")}" and is styled by ${offenders.length} rule(s) keyed off that class (e.g. ${example}). ` +
`At render, every sub-composition rule is scoped to [data-composition-id="${rootCompositionId}"] <selector>, so a selector whose leftmost part is the ROOT's own class becomes a descendant selector that cannot match the scoped element itself. ` +
`Since #1886 the producer preserves the authored root as an inner wrapper, so this no longer renders the scene unstyled, but #root is the shape the scoper special-cases and the registry blocks model. Use it so preview, render, and Studio agree.`,
selector: example,
fixHint: `Give the root id="root" and style it with \`#root { ... }\` plus plain descendant selectors (\`.kicker\`, \`#hero\`) — the runtime already scopes each sub-composition by data-composition-id, so a class namespace on the root is redundant.`,
snippet: truncateSnippet(rootTag.raw),
},
];
},
// root_composition_missing_duration_source
//
// The render engine (packages/engine/src/services/frameCapture.ts) needs a
// positive window.__hf.duration to know how many frames to capture. GSAP
// timelines set this automatically. Non-GSAP runtimes (CSS, WAAPI, Lottie)
// are now auto-inferred by the runtime too (see
// packages/core/src/runtime/init.ts resolveAdapterDurationFloorSeconds and
// the adapters' getInferredDurationSeconds) — so data-duration is optional
// wherever the runtime can work it out on its own.
//
// This rule fires for cases where the total render length is not reliably
// determinable without an explicit data-duration:
// - No GSAP timeline AND no data-duration AND no non-GSAP animation
// signal at all (nothing for any adapter to discover — render fails).
// - Three.js used with no data-duration (no discoverable AnimationClip
// duration in this codebase's adapter — see adapters/three.ts).
// - Any infinite CSS animation-iteration-count with no data-duration,
// EVEN when a finite CSS animation is present alongside it. An unbounded
// animation makes the intended total length ambiguous — the runtime will
// infer a finite sibling's length if one exists, but that's a fallback,
// not a declaration of intent, so we still require data-duration here.
// (This is intentionally stricter than the runtime's own inference.)
// Purely finite CSS/WAAPI animations and Lottie are excluded — the runtime
// infers those unambiguously, so requiring data-duration there would be a
// false positive against the runtime's own auto-inference. Note lint is
// advisory by default (see shouldBlockRender) — it only blocks render under
// --strict/--strict-all — so a strict flag here nudges toward an explicit,
// guaranteed-correct value without failing renders that would succeed.
// fallow-ignore-next-line complexity
({ rootTag, scripts, styles, tags, options }) => {
if (options.isSubComposition) return [];
if (!rootTag) return [];
// Not every file linted as a "root" HTML document is a video composition
// — e.g. a slideshow demo.html mounts <hyperframes-player src="index.html">
// with no data-composition-id of its own. Nothing to capture there, so
// there's no duration contract to enforce.
if (readDecodedAttr(rootTag.raw, "data-composition-id") === null) return [];
if (readAttr(rootTag.raw, "data-duration") !== null) return [];
// Strip comments before scanning for signals — a commented-out
// `.animate(...)` call or `/* animation: spin 2s infinite; */` must not
// satisfy the "has a duration source" check, or the composition still
// fails at render with zero duration despite lint passing.
const allScriptTexts = scripts.map((s) => stripJsComments(s.content));
const hasGsapTimeline = allScriptTexts.some((t) => /gsap\.timeline\s*\(/.test(t));
const hasRegisteredTimeline = allScriptTexts.some((t) =>
WINDOW_TIMELINE_ASSIGN_PATTERN.test(t),
);
// A GSAP timeline drives duration via window.__timelines regardless of
// data-duration — nothing to flag once one is registered.
if (hasGsapTimeline && hasRegisteredTimeline) return [];
const allCss = styles.map((s) => s.content).join("\n");
const allInlineStyles = tags.map((t) => readAttr(t.raw, "style") || "").join("\n");
const combinedCss = `${allCss}\n${allInlineStyles}`.replace(/\/\*[\s\S]*?\*\//g, "");
const usesLottie =
tags.some((t) => readAttr(t.raw, "data-lottie-src") !== null) ||
allScriptTexts.some((t) => /lottie\.(loadAnimation)\b|__hfLottie\b/.test(t));
const usesThree = allScriptTexts.some((t) => /\bTHREE\./.test(t));
// `.animate([...], ...)` catches the array-literal keyframes form;
// `.animate({...}, ...)` catches the object-literal (PropertyIndexedKeyframes)
// form; `.animate(someVar, ...)` catches keyframes built up in a variable
// first.
const usesWaapi = allScriptTexts.some((t) => /\.animate\s*\(\s*[[{$A-Za-z_]/.test(t));
const hasCssAnimationName = /\banimation(?:-name)?\s*:/.test(combinedCss);
const hasInfiniteCssAnimation =
/\banimation(?:-iteration-count)?\s*:[^;{}]*(?<![\w-])infinite(?![\w-])/.test(combinedCss);
const hasAnyNonGsapSignal = usesLottie || usesThree || usesWaapi || hasCssAnimationName;
if (!hasAnyNonGsapSignal) {
const derived = deriveDurationFromClips(tags, rootTag);
if (derived.source === "derived") {
return [
{
code: "root_composition_duration_derived",
severity: "warning",
message:
"Root composition has no data-duration and no GSAP timeline, so its length is taken from " +
`its clips: at least ${derived.seconds}s` +
(derived.pendingClips > 0
? `, and ${derived.pendingClips} clip(s) whose length is only known at runtime`
: "") +
".",
fixHint:
'Add data-duration="<seconds>" to the root element to set the length yourself.',
snippet: truncateSnippet(rootTag.raw),
},
];
}
// No GSAP timeline, no data-duration, and nothing for any adapter to
// discover — the composition has no source of truth for duration at
// all. This is the exact shape of the 27K "zero duration" render
// failures this rule exists to catch before render time.
return [
{
code: "root_composition_missing_duration_source",
severity: "error",
message:
"Root composition has no data-duration, no GSAP timeline, and no CSS/WAAPI/Lottie/Three.js " +
"animation for the runtime to infer a duration from. The render engine cannot determine " +
'how long to capture and will fail with "Composition has zero duration".',
fixHint:
'Add data-duration="<seconds>" to the root element, or add a paused GSAP timeline registered ' +
"on window.__timelines.",
snippet: truncateSnippet(rootTag.raw),
},
];
}
if (usesThree) {
// No AnimationMixer/AnimationClip discovery in the three.js adapter
// today (see adapters/three.ts) — genuinely not inferable.
return [
{
code: "root_composition_missing_duration_source",
severity: "error",
message:
"Root composition uses Three.js with no data-duration. The runtime cannot discover a " +
"Three.js scene's duration automatically (no AnimationClip/AnimationMixer inspection) — " +
'render will fail with "Composition has zero duration".',
fixHint: 'Add data-duration="<seconds>" to the root element.',
snippet: truncateSnippet(rootTag.raw),
},
];
}
if (hasInfiniteCssAnimation && !usesLottie && !usesWaapi) {
// An infinite/unbounded CSS animation makes the intended total length
// ambiguous, so we require an explicit data-duration even when a finite
// CSS animation is present alongside it. This is deliberately stricter
// than the runtime's own inference: the CSS adapter's
// getInferredDurationSeconds (see adapters/css.ts) returns the longest
// finite animation end-time when one exists (so a finite sibling would
// render at that length) and null when every animation is unbounded (so
// a render with no finite source fails outright). Either way the author
// hasn't declared how long the video should be — a decorative infinite
// spinner next to a 3s fade doesn't tell us the clip is meant to be 3s
// — so we flag it and let them state intent. The message stays honest
// about both outcomes rather than claiming the render always fails.
return [
{
code: "root_composition_missing_duration_source",
severity: "error",
message:
"Root composition uses a CSS animation with animation-iteration-count: infinite and no " +
"data-duration, so the intended total length is ambiguous. If a finite animation is also " +
"present the runtime infers that length; with no finite source the render fails with " +
'"Composition has zero duration". Declare the intended length explicitly.',
fixHint:
'Add data-duration="<seconds>" to the root element with the intended total length.',
snippet: truncateSnippet(rootTag.raw),
},
];
}
// Finite CSS animation, WAAPI .animate(), or Lottie — the runtime infers
// duration from these at render time (see resolveAdapterDurationFloorSeconds
// in runtime/init.ts). Not an error; data-duration is optional here.
return [];
},
// composition_heavy_overlay_count_high
// Field signal ts=1784040753 (#hyperframes-cli-feedback): a composition
// with ~40 heavy overlay DOM elements — `filter:blur`, oversized
// `radial-gradient`, and `clip-path` animations — captures solid-black for
// the first ~half of the render, recovering near the end. Reproduces
// identically via drawElement AND forced --no-browser-gpu screenshot
// capture AND `snapshot`, so the offender is the capture layer itself, not
// encoder/mux. Independent of duration (padding the timeline grows the bad
// zone proportionally, doesn't shift it). Reporter's workaround was to
// split into per-transition mini compositions + FFmpeg concat.
//
// Presence alone matters: opacity:0 and visibility:hidden overlays still
// contribute to the capture-layer regression, so they're counted-in. The
// only escape hatch is `display: none` — an element removed from the render
// tree can't feed the compositor. Warn at 25, well below the observed
// 40-element repro, to give authors lead time before hitting the bug.
// fallow-ignore-next-line complexity
({ tags, styles, rawSource, options }) => {
if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource)) return [];
const { classes: heavyClassTokens, ids: heavyIds } = collectHeavyOverlayHooks(styles);
let heavyCount = 0;
for (const tag of tags) {
if (HEAVY_OVERLAY_EXEMPT_TAGS.has(tag.name)) continue;
// Structural containers (root + mounted sub-compositions) aren't overlay
// content — the heavy children live inside them, and each such child is
// its own tag entry that we score directly. Counting the container too
// would double-attribute the risk to one authoring surface.
if (isCompositionRootOrMount(tag.raw)) continue;
// readJsonAttr lets a `style` value carry the opposite quote character
// (inline `background: url("x.png")` etc.), which readAttr would truncate.
const styleAttr = readJsonAttr(tag.raw, "style") ?? "";
// display:none removes the element from the render tree, so the capture
// layer never sees it — the only reliable way to keep an "unused" heavy
// overlay in the source without paying the compositor cost.
if (styleAttr && INLINE_STYLE_DISPLAY_NONE_PATTERN.test(styleAttr)) continue;
let heavy = false;
if (styleAttr && HEAVY_OVERLAY_CSS_PATTERN.test(styleAttr)) heavy = true;
if (!heavy && (heavyClassTokens.size > 0 || heavyIds.size > 0)) {
const classList = (readAttr(tag.raw, "class") || "").split(/\s+/).filter(Boolean);
if (classList.some((cls) => heavyClassTokens.has(cls))) heavy = true;
if (!heavy) {
const idValue = readAttr(tag.raw, "id");
if (idValue && heavyIds.has(idValue)) heavy = true;
}
}
if (heavy) heavyCount += 1;
}
if (heavyCount < HEAVY_OVERLAY_ELEMENT_COUNT_WARN) return [];
const splitTarget = options.isSubComposition
? "Split this sub-composition further into per-transition mini-compositions"
: "Split coherent scenes / transitions into separate .html files under compositions/";
return [
{
code: "composition_heavy_overlay_count_high",
severity: "warning",
message:
`This composition has ${heavyCount} elements carrying "heavy overlay" CSS ` +
`(filter:blur, radial-gradient, or clip-path). Field signal: a composition with ` +
`~40 such elements — including opacity:0 / visibility:hidden ones — captures ` +
`solid-black for the first ~half of the render, recovering near the end. Reproduces ` +
`identically via drawElement, forced screenshot capture, and snapshot, so the capture ` +
`layer itself is the offender (not encoder/mux). Independent of duration. Presence ` +
`alone matters; only display:none elements are excluded here.`,
fixHint:
`${splitTarget} and concat the pieces (FFmpeg or the runtime's slideshow) so each ` +
`capture only sees a small subset of heavy overlays at once. Even hidden overlays ` +
`(opacity:0 / visibility:hidden) contribute — either remove truly unused ones from ` +
`the source or scope them into their own per-transition sub-composition. If an ` +
`overlay is genuinely inert for the whole clip, use display:none so it never enters ` +
`the render tree. Field ref ts=1784040753 (#hyperframes-cli-feedback).`,
},
];
},
// root_zoom_rescales_a_fixed_canvas
//
// The capture frame is sized from the root's data-width/data-height, which are
// LAYOUT pixels. CSS `zoom` on the canvas itself (the root, or html/body above
// it) rescales the painted content inside that frame without changing the frame,
// so the two disagree and the author gets neither of the two things they might
// have meant.
//
// Measured at 0.8.71 on an 800x400 composition holding two 100x100 boxes at
// left:100 and left:600, rendered to a PNG sequence and the boxes located by
// colour:
//
// root zoom:0.5 canvas stays 800x400; boxes paint at (50,25) and (300,25),
// each 50x50 -- the composition occupies the top-left quarter
// and the rest of every frame is dead space.
// root zoom:2 canvas stays 800x400; the left:100 box paints at (200,100)
// at 200x200, and the left:600 box renders ZERO PIXELS --
// scaled to x=1200, outside a frame that is still 800 wide.
//
// The second case is the one worth an error: content that is inside the declared
// composition silently does not exist in the output, with nothing else in lint,
// check or the render log naming it.
//
// Deliberately NOT flagged: `zoom` on a descendant. Measured in the same run --
// a child at left:100 with zoom:2 paints at (200,100) at 200x200, which is
// exactly what CSS `zoom` specifies. It is honoured, not ignored, so a rule that
// fired on every `zoom` would be flagging correct authoring.
({ rootTag, tags, styles }) => {
if (!rootTag) return [];
const rootId = readAttr(rootTag.raw, "id");
const rootClasses = (readAttr(rootTag.raw, "class") || "").split(/\s+/).filter(Boolean);
const hits = canvasZoomHits(rootTag, tags, styles, rootId, rootClasses);
// `noUncheckedIndexedAccess` makes hits[0] `T | undefined`, and a length
// check does not narrow it — guard on the element itself.
const hit = hits[0];
if (!hit) return [];
const enlarging =
!hit.value.startsWith("-") && parseFloat(hit.value) > (hit.value.includes("%") ? 100 : 1);
return [
{
code: "root_zoom_rescales_a_fixed_canvas",
severity: "error",
message:
`\`zoom: ${hit.value}\` on ${hit.where} rescales the painted composition inside a frame that does not rescale with it. ` +
`The capture frame is sized from the root's data-width/data-height in LAYOUT pixels, and \`zoom\` changes only what is painted inside it, so ` +
(enlarging
? `content past the frame's edge renders zero pixels — it is inside the declared composition and absent from the output, with nothing else reporting it.`
: `the composition paints into part of the frame and the remainder of every output frame is dead space.`),
fixHint:
`Author the composition at its real size — set data-width/data-height (and the root's width/height) to the dimensions you want — and drop the canvas-level \`zoom\`. ` +
`To scale the OUTPUT without changing layout, pass \`--output-resolution\` to render, which supersamples. ` +
`\`zoom\` on descendants is fine and is not flagged: it is honoured exactly as specified.`,
snippet: hit.snippet,
},
];
},
// composition_exceeds_inspection_viewport_cap
//
// packages/cli/src/utils/compositionViewport.ts caps a parsed data-width /
// data-height at MAX_VIEWPORT_DIMENSION (4096) with a plain Math.min and no
// warning. captureCompositionFrame resolves its viewport through that helper,
// and check, validate, snapshot, compare and layout all capture through it;
// layout and motionShot carry their own independent Math.min(..., 4096).
//
// `render` does NOT go through it, and that asymmetry is the whole finding.
// Measured at 0.8.71 on a 5000x400 composition with 100x100 boxes at left:100
// and left:4500:
//
// render -> 5000x400 output, both boxes present.
// snapshot -> 4096x400 frame, the left:4500 box ABSENT.
//
// So the video is correct and the tools an author would reach for to check it
// silently cannot see the last 904 px. The failure direction is the awkward
// one: `check` comes back clean on a region it never rendered, and someone
// debugging a missing element through `snapshot` chases a difference that
// exists only in the instrument.
//
// A warning, not an error: the deliverable is fine, and a composition wider
// than 4096 can be entirely deliberate.
({ rootTag }) => {
if (!rootTag) return [];
const over: string[] = [];
for (const attr of ["data-width", "data-height"] as const) {
const raw = readAttr(rootTag.raw, attr);
if (!raw) continue;
const value = Number.parseInt(raw, 10);
if (Number.isFinite(value) && value > INSPECTION_VIEWPORT_CAP) {
over.push(`${attr}=${value}`);
}
}
if (over.length === 0) return [];
return [
{
code: "composition_exceeds_inspection_viewport_cap",
severity: "warning",
message:
`${over.join(" and ")} exceeds the ${INSPECTION_VIEWPORT_CAP}px viewport cap that check, validate, snapshot, compare and layout clamp to. ` +
`render is unaffected and produces the full size, so the video is correct — but every inspection command captures a ${INSPECTION_VIEWPORT_CAP}px-wide frame, ` +
`and anything beyond that is missing from what they report. Measured at 0.8.71: a 5000x400 composition renders 5000x400 with all content, ` +
`while snapshot returns 4096x400 with the element at left:4500 absent.`,
fixHint:
`Keep the authored size if the output needs it, and verify the region past ${INSPECTION_VIEWPORT_CAP}px from a render rather than from check/snapshot/compare — ` +
`a clean inspection result does not cover it. If the large canvas is only there to gain resolution, author at the layout size and pass ` +
`\`--output-resolution\` to render instead, which supersamples without changing layout.`,
snippet: truncateSnippet(rootTag.raw),
},
];
},
];
const CLIP_MEDIA_TAGS = new Set<string>(["img", "video", "audio"]);
/** The root's length from its timed clips, through the shared resolvers. A video or audio with no
* authored length is pending here (only the file knows it), so it is counted, not guessed. */
function deriveDurationFromClips(tags: OpenTag[], rootTag: OpenTag) {
const clipEnds: Array<number | null> = [];
for (const tag of tags) {
if (tag === rootTag) continue;
const startRaw = readAttr(tag.raw, "data-start");
if (startRaw === null) continue;
const start = Number(startRaw);
// A reference start ("intro+2") is resolved by the runtime; here it is a clip of unknown end.
if (!Number.isFinite(start)) {
clipEnds.push(null);
continue;
}
const getAttr = (name: string) => readAttr(tag.raw, name);
const authored = readAuthoredDurationSeconds(getAttr, start);
if (CLIP_MEDIA_TAGS.has(tag.name)) {
const { seconds } = resolveMediaDuration({
tag: tag.name as MediaTag,
authoredDurationSeconds: authored,
sourceDurationSeconds: null,
mediaStartSeconds: 0,
playbackRate: 1,
});
clipEnds.push(seconds === null ? null : start + seconds);
} else if (authored !== null && authored > 0) {
clipEnds.push(start + authored);
}
}
return resolveCompositionDuration({ authoredDurationSeconds: null, clipEndsSeconds: clipEnds });
}