@hyperframes/core 0.7.13 → 0.7.15

package/dist/lint/rules/composition.js

@@ -1,694 +0,0 @@
-import { findHtmlTag, readAttr, readJsonAttr, stripJsComments, truncateSnippet } from "../utils.js";
-import { COMPOSITION_VARIABLE_TYPES } from "../../core.types.js";
-// Agent guidance thresholds: warning-only nudges for files/tracks that become hard
-// to inspect and revise reliably in a single composition.
-const MAX_COMPOSITION_LINES = 300;
-const MAX_TIMED_ELEMENTS_PER_TRACK = 3;
-const TRACK_DENSITY_EXEMPT_TAGS = new Set(["audio", "script", "style", "video"]);
-function countPhysicalLines(source) {
-    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) {
-    return countPhysicalLines(source.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "<style></style>"));
-}
-export function isRegistrySourceFile(filePath) {
-    if (!filePath)
-        return false;
-    const normalized = filePath.replace(/\\/g, "/");
-    return /(?:^|\/)registry\/blocks\/([^/]+)\/\1\.html$/i.test(normalized);
-}
-export function isRegistryInstalledFile(rawSource) {
-    return /^\s*<!--\s*hyperframes-registry-item:[^>]*-->/i.test(rawSource.slice(0, 512));
-}
-function isCompositionRootOrMount(rawTag) {
-    return Boolean(readAttr(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) {
-    const out = [];
-    const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
-    const urlPattern = /\burl\(\s*(["']?)([^)"']+)\1\s*\)/g;
-    let m;
-    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) {
-    const out = [];
-    const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
-    const ruleHeader = /([^{}]+)\{/g;
-    let m;
-    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) {
-    const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
-    return (leftmost.match(/\.([\w-]+)/g) ?? []).map((c) => c.slice(1));
-}
-// 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, rootClasses) {
-    const offenders = [];
-    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;
-}
-export const compositionRules = [
-    // 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 = [];
-        const collect = (value) => {
-            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();
-        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();
-        for (const tag of tags) {
-            if (TRACK_DENSITY_EXEMPT_TAGS.has(tag.name))
-                continue;
-            if (isCompositionRootOrMount(tag.raw))
-                continue;
-            if (!readAttr(tag.raw, "data-start"))
-                continue;
-            const track = readAttr(tag.raw, "data-track-index");
-            if (!track)
-                continue;
-            trackCounts.set(track, (trackCounts.get(track) ?? 0) + 1);
-        }
-        const findings = [];
-        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;
-    },
-    // timed_element_missing_visibility_hidden
-    // fallow-ignore-next-line complexity
-    ({ tags }) => {
-        const findings = [];
-        for (const tag of tags) {
-            if (tag.name === "audio" || tag.name === "script" || tag.name === "style")
-                continue;
-            if (!readAttr(tag.raw, "data-start"))
-                continue;
-            if (readAttr(tag.raw, "data-composition-id"))
-                continue;
-            if (readAttr(tag.raw, "data-composition-src"))
-                continue;
-            const classAttr = readAttr(tag.raw, "class") || "";
-            const styleAttr = readAttr(tag.raw, "style") || "";
-            const hasClip = classAttr.split(/\s+/).includes("clip");
-            const hasHiddenStyle = /visibility\s*:\s*hidden/i.test(styleAttr) || /opacity\s*:\s*0/i.test(styleAttr);
-            if (!hasClip && !hasHiddenStyle) {
-                const elementId = readAttr(tag.raw, "id") || undefined;
-                findings.push({
-                    code: "timed_element_missing_visibility_hidden",
-                    severity: "info",
-                    message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has data-start but no class="clip", visibility:hidden, or opacity:0. Consider adding initial hidden state if the element should not be visible before its start time.`,
-                    elementId,
-                    fixHint: 'Add class="clip" (with CSS: .clip { visibility: hidden; }) or style="opacity:0" if the element should start hidden.',
-                    snippet: truncateSnippet(tag.raw),
-                });
-            }
-        }
-        return findings;
-    },
-    // deprecated_data_layer + deprecated_data_end
-    // fallow-ignore-next-line complexity
-    ({ tags }) => {
-        const findings = [];
-        for (const tag of tags) {
-            if (readAttr(tag.raw, "data-layer") && !readAttr(tag.raw, "data-track-index")) {
-                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. The runtime reads data-track-index.",
-                    snippet: truncateSnippet(tag.raw),
-                });
-            }
-            if (readAttr(tag.raw, "data-end") && !readAttr(tag.raw, "data-duration")) {
-                const elementId = readAttr(tag.raw, "id") || undefined;
-                findings.push({
-                    code: "deprecated_data_end",
-                    severity: "error",
-                    message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> uses data-end without data-duration. Use data-duration in source HTML.`,
-                    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 = [];
-        const splitDataAttrSelectorPattern = /\[data-composition-id=(["'])([^"'\]]+)\1\s+(data-[\w:-]+)=(["'])([^"'\]]*)\4\]/g;
-        const scan = (content) => {
-            splitDataAttrSelectorPattern.lastIndex = 0;
-            let match;
-            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(style.content);
-        for (const script of scripts)
-            scan(script.content);
-        return findings;
-    },
-    // template_literal_selector
-    ({ scripts }) => {
-        const findings = [];
-        for (const script of scripts) {
-            const templateLiteralSelectorPattern = /(?:querySelector|querySelectorAll)\s*\(\s*`[^`]*\$\{[^}]+\}[^`]*`\s*\)/g;
-            let tlMatch;
-            while ((tlMatch = templateLiteralSelectorPattern.exec(script.content)) !== 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(tlMatch[0]),
-                });
-            }
-        }
-        return findings;
-    },
-    // timed_element_missing_clip_class
-    // fallow-ignore-next-line complexity
-    ({ tags }) => {
-        const findings = [];
-        const skipTags = new Set(["audio", "video", "script", "style", "template"]);
-        for (const tag of tags) {
-            if (skipTags.has(tag.name))
-                continue;
-            // Skip composition hosts
-            if (readAttr(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",
-                severity: "error",
-                message: `<${tag.name}${elementId ? ` id="${elementId}"` : ""}> has timing attributes but no class="clip". The element will be visible for the entire composition instead of only during its scheduled time range.`,
-                elementId,
-                fixHint: 'Add class="clip" to the element. The HyperFrames runtime uses .clip to control visibility based on data-start/data-duration.',
-                snippet: truncateSnippet(tag.raw),
-            });
-        }
-        return findings;
-    },
-    // overlapping_clips_same_track
-    // fallow-ignore-next-line complexity
-    ({ tags }) => {
-        const findings = [];
-        const trackMap = new Map();
-        for (const tag of tags) {
-            const startStr = readAttr(tag.raw, "data-start");
-            const durationStr = readAttr(tag.raw, "data-duration");
-            const trackStr = readAttr(tag.raw, "data-track-index");
-            if (!startStr || !durationStr || !trackStr)
-                continue;
-            const start = Number(startStr);
-            const duration = Number(durationStr);
-            const track = trackStr;
-            // Skip non-numeric (relative timing references like "intro-comp")
-            if (Number.isNaN(start) || Number.isNaN(duration))
-                continue;
-            const clips = trackMap.get(track) || [];
-            clips.push({
-                start,
-                end: start + duration,
-                elementId: readAttr(tag.raw, "id") || undefined,
-                snippet: truncateSnippet(tag.raw) || "",
-            });
-            trackMap.set(track, clips);
-        }
-        for (const [track, clips] of trackMap) {
-            clips.sort((a, b) => a.start - b.start);
-            for (let i = 0; i < clips.length - 1; i++) {
-                const current = clips[i];
-                const next = clips[i + 1];
-                if (!current || !next)
-                    continue;
-                if (current.end > next.start) {
-                    findings.push({
-                        code: "overlapping_clips_same_track",
-                        severity: "error",
-                        message: `Track ${track}: clip ending at ${current.end}s overlaps with clip starting at ${next.start}s. Overlapping clips on the same track cause rendering conflicts.`,
-                        fixHint: "Adjust data-start or data-duration so clips on the same track do not overlap, or move one clip to a different data-track-index.",
-                    });
-                }
-            }
-        }
-        return findings;
-    },
-    // root_composition_missing_data_start
-    ({ rootTag, options }) => {
-        const findings = [];
-        if (options.isSubComposition)
-            return findings;
-        if (!rootTag)
-            return findings;
-        const compId = readAttr(rootTag.raw, "data-composition-id");
-        if (!compId)
-            return findings;
-        const hasStart = readAttr(rootTag.raw, "data-start") !== null;
-        if (!hasStart) {
-            findings.push({
-                code: "root_composition_missing_data_start",
-                severity: "error",
-                message: `Root composition "${compId}" is missing data-start. The runtime needs data-start="0" on the root element to begin playback.`,
-                fixHint: 'Add data-start="0" to the root composition element.',
-                snippet: truncateSnippet(rootTag.raw),
-            });
-        }
-        return findings;
-    },
-    // standalone_composition_wrapped_in_template
-    ({ rawSource, options }) => {
-        const findings = [];
-        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 = [];
-        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;
-    },
-    // requestanimationframe_in_composition
-    ({ scripts, rawSource, options }) => {
-        if (isRegistrySourceFile(options.filePath) || isRegistryInstalledFile(rawSource))
-            return [];
-        const findings = [];
-        for (const script of scripts) {
-            const stripped = stripJsComments(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 = [];
-        for (const tag of tags) {
-            const raw = readJsonAttr(tag.raw, "data-variable-values");
-            if (!raw)
-                continue;
-            let parsed;
-            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;
-    },
-    // 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.
-    // fallow-ignore-next-line complexity
-    ({ source }) => {
-        const htmlTag = findHtmlTag(source);
-        if (!htmlTag)
-            return [];
-        const raw = readJsonAttr(htmlTag.raw, "data-composition-variables");
-        if (!raw)
-            return [];
-        let parsed;
-        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(htmlTag.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(htmlTag.raw),
-                },
-            ];
-        }
-        const findings = [];
-        const knownTypes = new Set(COMPOSITION_VARIABLE_TYPES);
-        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(htmlTag.raw),
-                });
-                continue;
-            }
-            const e = entry;
-            const missing = [];
-            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(htmlTag.raw),
-                });
-            }
-        }
-        return findings;
-    },
-    // 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) => 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) => timed.some((t) => t.tag.index !== exceptIndex && t.end >= rootDuration - EPSILON);
-        const findings = [];
-        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 root — the whole scene renders unstyled (tiny text top-left, images
-    // at natural size). lint/validate/inspect evaluate the file in isolation (no
-    // scoping) and Studio previews each scene in its own iframe (no scoping), so the
-    // break is invisible until the composited MP4 render. 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 root — the scene renders unstyled (tiny text top-left, full-size images). ` +
-                    `lint/validate/inspect and Studio's per-frame iframe preview do not scope, so this passes every static check and looks correct in preview.`,
-                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 and breaks under scoping.`,
-                snippet: truncateSnippet(rootTag.raw),
-            },
-        ];
-    },
-];
-//# sourceMappingURL=composition.js.map