mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
* 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
1641 lines
77 KiB
TypeScript
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 });
|
|
}
|