fix(lint): consolidate lint and audit correctness (#2413)

* fix(lint): stop CSS comments in <style> from manufacturing phantom root tags

extractOpenTags scans raw source text with a flat regex that has no
concept of <style>/<script> block boundaries, so a CSS comment like
`/* <g> wrapper */` inside a <style> block reads as a real open tag.
findRootTag consumes that flat tag list and only skips tags literally
named script/style/meta/link/title, so the phantom <g> tag (not in
that skip list) wins the "first non-ignored body tag" search and gets
returned as the composition root instead of the real one that follows.

This manufactured root_missing_composition_id and root_missing_dimensions
(the phantom tag has neither) plus head_leaked_text (the leaked-text
scan slices up to the phantom tag's position, landing inside the
<style> block before its real closing tag, so the raw CSS text reads
as leaked markup) on an otherwise valid sub-composition — reported
with an exact bisected repro: a <template>-wrapped SVG sub-composition
whose <style> block comments reference an inner <g> element.

Fix: compute <style>/<script> content spans up front (reusing the
existing extractBlocks + STYLE_BLOCK_PATTERN/SCRIPT_BLOCK_PATTERN) and
skip any TAG_PATTERN match that falls inside one, before it ever
reaches findRootTag or any other extractOpenTags consumer. Same shape
as the prior fix for a leading <svg> defs block being mistaken for the
root (8ee4b7df) — this closes a sibling gap in the same function.

Test: new regression case with a <style> block containing a `/* <g> */`
comment ahead of an <svg data-composition-id> root, asserting none of
the three findings fire. Full lint package suite (318 tests) passes.

* feat(lint): flag duplicate data-composition-id values

Declaring data-composition-id on more than one element (commonly the <meta>
tag from the quickstart template AND the root <div> added to satisfy
root_missing_composition_id) is a silent collision: `compositions --json`
returns two entries for the same id (one duration:0) and inspect/snapshot
crash with "Cannot read properties of undefined (reading totalDuration)".
Lint passed clean through all of it.

New rule `duplicate_composition_id`: group elements by data-composition-id
value and error on any value shared by 2+ elements, naming the id and calling
out the meta-vs-root collision in the fixHint. 3 tests: dup fires, single id
passes, two distinct ids don't collide. (Implemented via Codex; verified
independently: 111 lint tests pass, oxfmt/oxlint clean.)

* fix(audits): avoid caption false positives

* fix(lint): ignore proxy-label tween overlaps

* fix(cli): preserve the five-percent text audit floor

* fix(lint): preserve proxy identity across lexical scopes

* fix(cli): audit only directly painted text

* fix(lint): compare live composition ids canonically

* fix(lint): preserve expanded proxy identities

* fix(cli): measure directly painted text geometry

* fix(lint): preserve first duplicate attribute value

* fix(lint): keep shared proxy identity across helpers

* fix(parsers): preserve expanded proxy identity

* fix(lint): decode composition IDs consistently
This commit is contained in:
Miguel Ángel
2026-07-14 20:13:01 -04:00
committed by GitHub
parent 37e1b26434
commit ada878fdcd
16 changed files with 759 additions and 64 deletions
@@ -219,10 +219,10 @@
const text = textContentFor(element, directOnly);
if (!text) return false;
if (directOnly) return true;
for (const child of Array.from(element.children)) {
if (isVisibleElement(child) && textContentFor(child)) return false;
}
return true;
// Aggregate text may come exclusively from descendants (including hidden
// captions). The container itself does not paint that text and must not be
// audited as though it did.
return textContentFor(element, true).length > 0;
}
function textClientRects(element, directOnly) {
@@ -436,9 +436,9 @@
}
function textOverflowIssues(element, root, rootRect, time, tolerance) {
const textRect = textRectFor(element);
const textRect = textRectFor(element, true);
if (!textRect) return [];
const text = textContentFor(element);
const text = textContentFor(element, true);
const selector = selectorFor(element);
const issues = [];
@@ -571,7 +571,7 @@
// (low colour alpha) is decorative and exempt, as are elements opted out with
// data-layout-allow-overlap.
function isSolidTextBlock(element) {
if (!isVisibleElement(element) || !hasOwnTextCandidate(element)) return false;
if (!isVisibleElement(element) || !hasOwnTextCandidate(element, true)) return false;
if (hasAllowOverlapFlag(element)) return false;
return colorAlpha(getComputedStyle(element).color) >= 0.35;
}
@@ -580,7 +580,7 @@
const blocks = [];
for (const element of Array.from(root.querySelectorAll("*"))) {
if (!isSolidTextBlock(element)) continue;
const rect = textRectFor(element);
const rect = textRectFor(element, true);
if (rect) blocks.push({ element, rect });
}
return blocks;
@@ -983,9 +983,9 @@
function occludedTextIssue(element, time) {
if (hasAllowOcclusionFlag(element)) return null;
if (!hasVisibleTextInk(element)) return null;
const textRect = textRectFor(element);
const textRect = textRectFor(element, true);
if (!textRect) return null;
const text = textContentFor(element);
const text = textContentFor(element, true);
const { occluder, coveredFraction } = occlusionCoverage(element, textRect);
if (!occluder) return null;
if (!isAtomicLabel(text) && coveredFraction < PROSE_COVERAGE_FLOOR) return null;
@@ -1016,9 +1016,9 @@
// paints the glyphs; a `background-clip: text` with no gradient/image and no
// opaque background-color paints nothing, so it stays reportable.
function invisibleTextIssue(element, time) {
const textRect = textRectFor(element);
const textRect = textRectFor(element, true);
if (!textRect) return null;
const text = textContentFor(element);
const text = textContentFor(element, true);
if (!text) return null;
const cs = getComputedStyle(element);
// Vendor computed-style props are read by property (camelCase), matching
@@ -1141,8 +1141,8 @@
if (escapedElements.has(element)) continue;
// Ownership is geometric and strict-mutex: any text breach past canvas_overflow's own
// tolerance cedes the element to canvas_overflow; in-bounds text leaves the panel finding.
if (hasOwnTextCandidate(element)) {
const textRect = textRectFor(element);
if (hasOwnTextCandidate(element, true)) {
const textRect = textRectFor(element, true);
if (textRect && overflowFor(textRect, rootRect, tolerance)) continue;
}
const rect = toRect(element.getBoundingClientRect());
@@ -1372,7 +1372,7 @@
document.body;
const rootRect = rootRectFor(root);
const elements = Array.from(root.querySelectorAll("*")).filter((element) =>
isVisibleElement(element),
isVisibleElement(element, 0.05),
);
const issues = [];
@@ -242,6 +242,31 @@ describe("layout-audit.browser", () => {
]),
);
});
it("does not expand a parent's overflow geometry to a positioned descendant", () => {
document.body.innerHTML = `
<div id="root" data-composition-id="main" data-width="640" data-height="360">
<div id="headline">Visible copy<span id="positioned-copy">Positioned copy</span></div>
</div>
`;
installGeometry(
{
root: rect({ left: 0, top: 0, width: 640, height: 360 }),
headline: rect({ left: 40, top: 60, width: 200, height: 40 }),
"positioned-copy": rect({ left: 700, top: 60, width: 160, height: 40 }),
headlineText: rect({ left: 40, top: 60, width: 120, height: 40 }),
"positioned-copyText": rect({ left: 700, top: 60, width: 160, height: 40 }),
text: rect({ left: 40, top: 60, width: 820, height: 40 }),
},
{ "positioned-copy": { position: "absolute" } },
);
installAuditScript();
const parentOverflow = runAudit().find(
(issue) => issue.code === "canvas_overflow" && issue.selector === "#headline",
);
expect(parentOverflow).toBeUndefined();
});
});
it("is inert unless text or media candidates are explicitly requested", () => {
@@ -1309,7 +1334,11 @@ function auditOverlapScene(options: {
selected = node;
},
getClientRects() {
const id = (selected as Element | null)?.id ?? "";
const element =
selected?.nodeType === Node.TEXT_NODE
? selected.parentElement
: (selected as Element | null);
const id = element?.id ?? "";
return textRects[id]
? ([textRects[id]] as unknown as DOMRectList)
: ([] as unknown as DOMRectList);
@@ -1389,6 +1418,28 @@ describe("layout-audit.browser occlusion", () => {
expect(issues.some((issue) => issue.code === "text_occluded")).toBe(false);
});
it("does not treat a visible container as painted text when its only text child is hidden", () => {
document.body.innerHTML = `
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<div id="caption-container"><span id="caption">Hidden caption</span></div>
<div id="overlay"></div>
</div>
`;
installOcclusionGeometry({
styleOverrides: {
caption: { opacity: "0" },
overlay: { backgroundColor: "rgb(10, 10, 10)" },
},
headlineTextRect: rect({ left: 200, top: 500, width: 600, height: 80 }),
topmostId: "overlay",
textRectElementId: "caption-container",
});
installAuditScript();
const issues = runAudit();
expect(issues.some((issue) => issue.code === "text_occluded")).toBe(false);
});
it("carries the fully-covered fraction when the occluder hits every probe point", () => {
const occluded = auditOcclusionScene({
overlayStyle: { backgroundColor: "rgb(10, 10, 10)" },
@@ -1450,6 +1501,47 @@ describe("layout-audit.browser occlusion", () => {
expect(runAudit().some((issue) => issue.code === "text_occluded")).toBe(false);
});
it("audits only a container's direct text when a hidden descendant also has text", () => {
document.body.innerHTML = `
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<div id="headline">Visible copy<span id="hidden-copy">Hidden copy</span></div>
<div id="overlay"></div>
</div>
`;
installOcclusionGeometry({
styleOverrides: {
"hidden-copy": { opacity: "0" },
overlay: { backgroundColor: "rgb(10, 10, 10)" },
},
headlineTextRect: rect({ left: 200, top: 500, width: 600, height: 80 }),
topmostId: "overlay",
});
installAuditScript();
const issue = runAudit().find((candidate) => candidate.code === "text_occluded");
expect(issue?.text).toBe("Visible copy");
});
it("does not expand a container's text audit to a positioned descendant", () => {
document.body.innerHTML = `
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
<div id="headline">Visible copy<span id="positioned-copy">Positioned copy</span></div>
<div id="overlay"></div>
</div>
`;
installOcclusionGeometry({
styleOverrides: {
"positioned-copy": { position: "absolute" },
overlay: { backgroundColor: "rgb(10, 10, 10)" },
},
headlineTextRect: rect({ left: 200, top: 500, width: 600, height: 80 }),
topmostId: "overlay",
});
installAuditScript();
const issues = runAudit().filter((candidate) => candidate.code === "text_occluded");
const headlineIssue = issues.find((candidate) => candidate.selector === "#headline");
expect(headlineIssue?.text).toBe("Visible copy");
});
it("does not count a low-alpha gradient overlay (grid/scrim) as an opaque occluder", () => {
const issues = auditOcclusionScene({
overlayStyle: {
@@ -1520,6 +1612,7 @@ describe("layout-audit.browser occlusion", () => {
},
headlineTextRect: rect({ left: 200, top: 500, width: 600, height: 80 }),
topmostId: "overlay",
textRectElementId: "inner",
});
installAuditScript();
expect(runAudit().some((issue) => issue.code === "text_occluded")).toBe(true);
@@ -1687,6 +1780,7 @@ function installOcclusionGeometry(options: {
styleOverrides: Record<string, Partial<Record<string, string>>>;
headlineTextRect: DOMRect;
topmostId: string;
textRectElementId?: string;
}): void {
const baseStyle: Record<string, string> = {
display: "block",
@@ -1733,7 +1827,11 @@ function installOcclusionGeometry(options: {
selected = node;
},
getClientRects() {
return (selected as Element | null)?.id === "headline"
const selectedElement =
selected?.nodeType === Node.TEXT_NODE
? (selected.parentElement as Element | null)
: (selected as Element | null);
return selectedElement?.id === (options.textRectElementId ?? "headline")
? ([options.headlineTextRect] as unknown as DOMRectList)
: ([] as unknown as DOMRectList);
},
@@ -1864,6 +1962,7 @@ async function runContrastAudit(): Promise<Array<Record<string, unknown>>> {
interface AuditIssue {
code: string;
selector: string;
text?: string;
containerSelector?: string;
overflow?: Record<string, number>;
message?: string;
@@ -1880,6 +1979,20 @@ function runAudit(): AuditIssue[] {
return audit({ time: 1, tolerance: 2 });
}
function selectedRangeElement(selected: Node | null): Element | null {
return selected?.nodeType === Node.TEXT_NODE
? (selected.parentElement as Element | null)
: (selected as Element | null);
}
function rangeTextRect(selected: Node | null, rects: Record<string, DOMRect>): DOMRect | undefined {
const element = selectedRangeElement(selected);
if (element?.id === "ignored") return rects.ignored;
if (selected?.nodeType === Node.TEXT_NODE && element?.id)
return rects[`${element.id}Text`] ?? rects.text;
return rects.text;
}
function installGeometry(
rects: Record<string, DOMRect>,
styleOverrides: Record<string, Partial<CSSStyleDeclaration>> = {},
@@ -1934,8 +2047,7 @@ function installGeometry(
selected = node;
},
getClientRects() {
const element = selected as Element | null;
const textRect = element?.id === "ignored" ? rects.ignored : rects.text;
const textRect = rangeTextRect(selected, rects);
return textRect ? ([textRect] as unknown as DOMRectList) : ([] as unknown as DOMRectList);
},
detach() {},
+2 -2
View File
@@ -3,7 +3,7 @@ import {
parseHtmlStructure,
findRootTag,
collectCompositionIds,
readAttr,
readDecodedAttr,
stripHtmlComments,
} from "./utils";
import type { OpenTag, ExtractedBlock } from "./utils";
@@ -66,7 +66,7 @@ export function buildLintContext(html: string, options: HyperframeLinterOptions
const scripts = structure.scripts;
const compositionIds = collectCompositionIds(tags);
const rootTag = findRootTag(source, tags);
const rootCompositionId = readAttr(rootTag?.raw || "", "data-composition-id");
const rootCompositionId = readDecodedAttr(rootTag?.raw || "", "data-composition-id");
return {
source,
@@ -190,6 +190,89 @@ describe("composition rules", () => {
});
});
describe("duplicate_composition_id", () => {
it("flags a meta tag and root div sharing the same data-composition-id", async () => {
const html = `<!DOCTYPE html>
<html>
<head>
<meta name="composition-id" data-composition-id="x">
</head>
<body>
<div data-composition-id="x" data-width="1920" data-height="1080" data-start="0" data-duration="1" data-no-timeline></div>
</body>
</html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "duplicate_composition_id");
expect(finding).toBeDefined();
expect(finding?.severity).toBe("error");
});
it("does not flag a single valid composition id", async () => {
const html = `<!DOCTYPE html>
<html>
<body>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="1" data-no-timeline></div>
</body>
</html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "duplicate_composition_id");
expect(finding).toBeUndefined();
});
it("does not flag distinct composition ids in one file", async () => {
const html = `<!DOCTYPE html>
<html>
<body>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="5" data-no-timeline>
<div data-composition-id="scene" data-composition-src="compositions/scene.html" data-start="0" data-duration="5"></div>
</div>
</body>
</html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "duplicate_composition_id");
expect(finding).toBeUndefined();
});
it("ignores composition ids inside inert template content", async () => {
const html = `<!DOCTYPE html>
<html><body>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="1" data-no-timeline></div>
<template><div data-composition-id="main"></div></template>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "duplicate_composition_id");
expect(finding).toBeUndefined();
});
it("flags entity-equivalent composition ids", async () => {
const html = `<!DOCTYPE html>
<html><body>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="1" data-no-timeline></div>
<meta data-composition-id="&#109;ain">
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "duplicate_composition_id");
expect(finding).toBeDefined();
});
it("uses the browser's first value for duplicate attributes", async () => {
const html = `<!DOCTYPE html>
<html><body>
<div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="1" data-no-timeline></div>
<meta data-composition-id="main" data-composition-id="other">
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "duplicate_composition_id");
expect(finding).toBeDefined();
});
});
it("reports error when querySelector uses template literal variable", async () => {
const html = `
<html><body>
+46 -5
View File
@@ -2,6 +2,7 @@ import type { LintContext, HyperframeLintFinding, ExtractedBlock, OpenTag } from
import {
findHtmlTag,
readAttr,
readDecodedAttr,
readJsonAttr,
stripJsComments,
truncateSnippet,
@@ -48,7 +49,7 @@ export function isRegistryInstalledFile(rawSource: string): boolean {
function isCompositionRootOrMount(rawTag: string): boolean {
return Boolean(
readAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src"),
readDecodedAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src"),
);
}
@@ -156,7 +157,47 @@ function declaredIdsForBindingCheck(tags: readonly OpenTag[]): Set<string> | nul
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,
);
}
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;
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
@@ -285,7 +326,7 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
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 (readDecodedAttr(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") || "";
@@ -400,7 +441,7 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
for (const tag of tags) {
if (skipTags.has(tag.name)) continue;
// Skip composition hosts
if (readAttr(tag.raw, "data-composition-id")) continue;
if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
if (readAttr(tag.raw, "data-composition-src")) continue;
const hasStart = readAttr(tag.raw, "data-start") !== null;
@@ -483,7 +524,7 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
const findings: HyperframeLintFinding[] = [];
if (options.isSubComposition) return findings;
if (!rootTag) return findings;
const compId = readAttr(rootTag.raw, "data-composition-id");
const compId = readDecodedAttr(rootTag.raw, "data-composition-id");
if (!compId) return findings;
const hasStart = readAttr(rootTag.raw, "data-start") !== null;
if (!hasStart) {
@@ -919,7 +960,7 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
// — 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 (readAttr(rootTag.raw, "data-composition-id") === null) return [];
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
+37
View File
@@ -214,6 +214,29 @@ describe("core rules", () => {
expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
});
it("does not mistake a <tag>-shaped CSS comment inside <style> for the composition root", async () => {
// Regression: a CSS comment referencing an SVG tag name (e.g. `/* <g> wrapper */`)
// inside a <style> block reads as a real open tag to the flat TAG_PATTERN scan,
// manufacturing a phantom root before the real composition root and firing
// root_missing_composition_id/root_missing_dimensions/head_leaked_text on an
// otherwise valid sub-composition.
const html = `
<html><body>
<style>
/* <g> wrapper for icon groups */
.icon { fill: currentColor; }
</style>
<svg id="root" data-composition-id="c1" data-width="1920" data-height="1080">
<g class="icon"></g>
</svg>
<script>window.__timelines = window.__timelines || {};</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "root_missing_composition_id")).toBeUndefined();
expect(result.findings.find((f) => f.code === "root_missing_dimensions")).toBeUndefined();
expect(result.findings.find((f) => f.code === "head_leaked_text")).toBeUndefined();
});
it("reports error when timeline registry is missing", async () => {
const html = `
<html><body>
@@ -778,6 +801,20 @@ body {
expect(finding).toBeUndefined();
});
it("matches timeline keys against browser-decoded composition ids", async () => {
const html = `
<html><body>
<div data-composition-id="&#99;1" data-width="1920" data-height="1080"></div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
expect(result.findings.find((f) => f.code === "timeline_id_mismatch")).toBeUndefined();
});
it("accepts object-literal timeline registration and extracts its keys", async () => {
const html = `
<html><body>
+8 -12
View File
@@ -2,6 +2,7 @@ import type { LintContext, HyperframeLintFinding } from "../context";
import postcss from "postcss";
import {
readAttr,
readDecodedAttr,
truncateSnippet,
stripJsComments,
extractCompositionIdsFromCss,
@@ -40,7 +41,7 @@ function isStudioTimelineElement(tag: { raw: string; name: string }): boolean {
function describeStudioElement(tag: { raw: string; name: string }): string {
const parts = [`<${tag.name}`];
const className = readAttr(tag.raw, "class");
const compositionId = readAttr(tag.raw, "data-composition-id");
const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
const dataStart = readAttr(tag.raw, "data-start");
const dataTrack = readAttr(tag.raw, "data-track-index") ?? readAttr(tag.raw, "data-track");
@@ -203,7 +204,7 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
// root_missing_composition_id + root_missing_dimensions
({ rootTag }) => {
const findings: HyperframeLintFinding[] = [];
if (!rootTag || !readAttr(rootTag.raw, "data-composition-id")) {
if (!rootTag || !readDecodedAttr(rootTag.raw, "data-composition-id")) {
findings.push({
code: "root_missing_composition_id",
severity: "error",
@@ -300,15 +301,10 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
},
// timeline_id_mismatch
({ source }) => {
({ source, compositionIds }) => {
const findings: HyperframeLintFinding[] = [];
const htmlCompIds = new Set<string>();
const htmlCompIds = new Set(compositionIds);
const timelineRegKeys = new Set<string>();
const compIdRe = /data-composition-id\s*=\s*["']([^"']+)["']/gi;
let m: RegExpExecArray | null;
while ((m = compIdRe.exec(source)) !== null) {
if (m[1]) htmlCompIds.add(m[1]);
}
for (const key of extractTimelineRegistryKeys(source)) {
timelineRegKeys.add(key);
}
@@ -369,7 +365,7 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
for (const tag of tags) {
const src = readAttr(tag.raw, "data-composition-src");
if (!src) continue;
if (readAttr(tag.raw, "data-composition-id")) continue;
if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
findings.push({
code: "host_missing_composition_id",
severity: "error",
@@ -452,8 +448,8 @@ export const coreRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
code: "studio_missing_editable_id",
severity: "warning",
message: `${descriptor} has no id, so Studio cannot use a stable edit target for its timeline and canvas controls.`,
selector: readAttr(tag.raw, "data-composition-id")
? `[data-composition-id="${readAttr(tag.raw, "data-composition-id")}"]`
selector: readDecodedAttr(tag.raw, "data-composition-id")
? `[data-composition-id="${readDecodedAttr(tag.raw, "data-composition-id")}"]`
: undefined,
fixHint:
'Add a stable, human-readable id such as id="hero-title" or id="scene-1-card" to every timeline-visible element you want agents or Studio to edit.',
+86
View File
@@ -998,6 +998,92 @@ describe("GSAP rules", () => {
expect(finding).toBeUndefined();
});
it("does NOT report overlapping_gsap_tweens for distinct loop-built DOM targets", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080">
<div id="caption-card-0"></div>
<div id="caption-card-1"></div>
</div>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
for (let i = 0; i < 2; i++) {
const card = document.getElementById("caption-card-" + i);
tl.to(card, { opacity: 1, duration: 1 }, i * 0.5);
}
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "overlapping_gsap_tweens");
expect(finding).toBeUndefined();
});
it("does NOT report overlapping_gsap_tweens for distinct object proxy drivers", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
const particles = { value: 0 };
const grain = { value: 0 };
tl.to(particles, { value: 1, duration: 2, ease: "none" }, 0);
tl.to(grain, { value: 1, duration: 2, ease: "none" }, 0);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "overlapping_gsap_tweens");
expect(finding).toBeUndefined();
});
it("reports overlapping_gsap_tweens for the same object proxy driver", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
const driver = { value: 0 };
tl.to(driver, { value: 1, duration: 2, ease: "none" }, 0);
tl.to(driver, { value: 2, duration: 2, ease: "none" }, 0.5);
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "overlapping_gsap_tweens");
expect(finding).toBeDefined();
});
it("does not conflate same-named object proxies from sibling scopes", async () => {
const html = `
<html><body>
<div data-composition-id="c1" data-width="1920" data-height="1080"></div>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
(() => {
const driver = { value: 0 };
tl.to(driver, { value: 1, duration: 2, ease: "none" }, 0);
})();
(() => {
const driver = { value: 0 };
tl.to(driver, { value: 1, duration: 2, ease: "none" }, 0.5);
})();
window.__timelines["c1"] = tl;
</script>
</body></html>`;
const result = await lintHyperframeHtml(html);
const finding = result.findings.find((f) => f.code === "overlapping_gsap_tweens");
expect(finding).toBeUndefined();
});
it("warns when an opacity exit ends at a clip start boundary without a hard kill", async () => {
const html = `
<html><body>
+19 -3
View File
@@ -1,6 +1,7 @@
interface LintParsedGsap {
animations: Array<{
targetSelector: string;
targetIdentity?: string;
method: string;
position: number | string;
properties: Record<string, number | string>;
@@ -27,6 +28,7 @@ import type { HyperframeLintFinding, LintRule } from "../types";
import type { OpenTag } from "../utils";
import {
readAttr,
readDecodedAttr,
truncateSnippet,
stripJsComments,
hasCaptionStyles,
@@ -38,6 +40,7 @@ import {
type GsapWindow = {
targetSelector: string;
targetIdentity?: string;
position: number;
end: number;
properties: string[];
@@ -61,6 +64,16 @@ const SCENE_BOUNDARY_EPSILON_SECONDS = 0.05;
// overlap analysis must never treat them as one.
const UNRESOLVED_TARGET = "__unresolved__";
// Parser labels for object-proxy tweens describe their role, not target
// identity. Two independent proxies can both be labelled `dwell/hold` (or the
// same driven DOM channel), so equality cannot prove they conflict.
function targetHasNoStableIdentity(selector: string, identity?: string): boolean {
if (identity) return false;
return (
selector === UNRESOLVED_TARGET || selector === "dwell/hold" || selector.startsWith("proxy → ")
);
}
// ── GSAP parsing utilities ─────────────────────────────────────────────────
function countClassUsage(tags: OpenTag[]): Map<string, number> {
@@ -137,6 +150,7 @@ async function extractGsapWindows(script: string): Promise<GsapWindow[]> {
animation.method === "set" ? 0 : (animation.duration ?? 0) * cycleCount;
windows.push({
targetSelector: animation.targetSelector,
targetIdentity: animation.targetIdentity,
position: animation.position,
end: animation.position + effectiveDuration,
properties: Object.keys(animation.properties),
@@ -259,7 +273,7 @@ function findTagEnd(source: string, tag: OpenTag): number {
function collectCompositionRanges(source: string, tags: OpenTag[]): CompositionRange[] {
return tags
.map((tag) => {
const id = readAttr(tag.raw, "data-composition-id");
const id = readDecodedAttr(tag.raw, "data-composition-id");
if (!id) return null;
return {
id,
@@ -593,12 +607,14 @@ export const gsapRules: LintRule<LintContext>[] = [
if (left.end <= left.position) continue;
// Unresolved targets are unknown elements: two of them are not provably
// the same element, so an overlap between them cannot be asserted.
if (left.targetSelector === UNRESOLVED_TARGET) continue;
if (targetHasNoStableIdentity(left.targetSelector, left.targetIdentity)) continue;
for (let j = i + 1; j < gsapWindows.length; j++) {
const right = gsapWindows[j];
if (!right) continue;
if (right.end <= right.position) continue;
if (left.targetSelector !== right.targetSelector) continue;
const leftIdentity = left.targetIdentity ?? left.targetSelector;
const rightIdentity = right.targetIdentity ?? right.targetSelector;
if (leftIdentity !== rightIdentity) continue;
const overlapStart = Math.max(left.position, right.position);
const overlapEnd = Math.min(left.end, right.end);
if (overlapEnd <= overlapStart) continue;
+2 -2
View File
@@ -1,5 +1,5 @@
import type { LintContext, HyperframeLintFinding } from "../context";
import { readAttr, truncateSnippet, isMediaTag } from "../utils";
import { readAttr, readDecodedAttr, truncateSnippet, isMediaTag } from "../utils";
function escapeRegExp(value: string): string {
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -308,7 +308,7 @@ export const mediaRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> =
if (tag.name === "video" || tag.name === "audio") continue;
if (voidElements.has(tag.name)) continue;
// Skip the composition root — it uses data-start as a playback anchor, not as a clip timer
if (readAttr(tag.raw, "data-composition-id")) continue;
if (readDecodedAttr(tag.raw, "data-composition-id")) continue;
if (readAttr(tag.raw, "data-start")) {
timedTagPositions.push({
name: tag.name,
+2 -2
View File
@@ -1,6 +1,6 @@
import type { LintContext, HyperframeLintFinding } from "../context";
import type { LintRule } from "../types";
import { readAttr } from "../utils";
import { readAttr, readDecodedAttr } from "../utils";
import {
parseSlideshowManifest,
resolveSlideshow,
@@ -30,7 +30,7 @@ function parseTiming(raw: string): { start: number; duration: number } | null {
function collectCompositionIdScenes(ctx: LintContext, seen: Set<string>, out: Scene[]): void {
for (const tag of ctx.tags) {
const compositionId = readAttr(tag.raw, "data-composition-id");
const compositionId = readDecodedAttr(tag.raw, "data-composition-id");
if (!compositionId || !isSceneLikeCompositionId(compositionId) || seen.has(compositionId))
continue;
const timing = parseTiming(tag.raw);
+19 -3
View File
@@ -121,7 +121,7 @@ export function findRootTag(source: string, parsedTags?: readonly OpenTag[]): Op
const bodyTag = tags.find((tag) => tag.name === "body");
if (
bodyTag &&
(readAttr(bodyTag.raw, "data-composition-id") ||
(readDecodedAttr(bodyTag.raw, "data-composition-id") ||
readAttr(bodyTag.raw, "data-width") ||
readAttr(bodyTag.raw, "data-height"))
) {
@@ -148,7 +148,7 @@ export function findRootTag(source: string, parsedTags?: readonly OpenTag[]): Op
// still eligible as the root.
if (
tag.name === "svg" &&
!readAttr(tag.raw, "data-composition-id") &&
!readDecodedAttr(tag.raw, "data-composition-id") &&
!readAttr(tag.raw, "data-width") &&
!readAttr(tag.raw, "data-height")
) {
@@ -173,6 +173,22 @@ export function readAttr(tagSource: string, attr: string): string | null {
return match?.[1] || null;
}
/** Read an HTML attribute using browser-equivalent character-reference decoding. */
export function readDecodedAttr(tagSource: string, attr: string): string | null {
if (!tagSource) return null;
let value: string | null = null;
const parser = new Parser(
{
onattribute(name, decodedValue) {
if (value === null && name.toLowerCase() === attr.toLowerCase()) value = decodedValue;
},
},
{ decodeEntities: true, lowerCaseAttributeNames: false, lowerCaseTags: true },
);
parser.end(tagSource);
return value;
}
/**
* Read an attribute that may legitimately contain the opposite quote
* character. `readAttr` truncates `data-variable-values='{"title":"Hello"}'`
@@ -200,7 +216,7 @@ export function readJsonAttr(tagSource: string, attr: string): string | null {
export function collectCompositionIds(tags: OpenTag[]): Set<string> {
const ids = new Set<string>();
for (const tag of tags) {
const compId = readAttr(tag.raw, "data-composition-id");
const compId = readDecodedAttr(tag.raw, "data-composition-id");
if (compId) ids.add(compId);
}
return ids;
+15 -4
View File
@@ -73,14 +73,20 @@ function collectPatternNames(pattern: Node, out: Set<string>): void {
else if (pattern?.type === "RestElement") collectPatternNames(pattern.argument, out);
}
function boundPatterns(node: Node): Node[] {
if (isFunctionNode(node)) return node.params ?? [];
if (node.type === "VariableDeclarator") return [node.id];
if (node.type === "CatchClause") return [node.param];
if (node.type === "AssignmentExpression" && node.left?.type === "Identifier") return [node.left];
return [];
}
/** Every identifier name bound anywhere inside the subtree (fn params, declared vars, catch params). */
function collectBoundNames(root: Node): Set<string> {
const names = new Set<string>();
const visit = (node: Node): Node => {
if (!isNode(node)) return node;
if (isFunctionNode(node)) for (const p of node.params ?? []) collectPatternNames(p, names);
else if (node.type === "VariableDeclarator") collectPatternNames(node.id, names);
else if (node.type === "CatchClause") collectPatternNames(node.param, names);
for (const pattern of boundPatterns(node)) collectPatternNames(pattern, names);
transformChildren(node, visit);
return node;
};
@@ -339,8 +345,13 @@ function expandBody(
ctx: ExpandCtx,
): Node[] {
const block = substituteParams(cloneNode({ type: "BlockStatement", body: bodyStmts }), bindings);
tagProvenance(block, prov);
tagTimelineCalls(block.body, prov, ctx);
return expandStatements(block.body, { ...ctx, depth: ctx.depth + 1 });
block.body = expandStatements(block.body, { ...ctx, depth: ctx.depth + 1 });
// Keep each synthetic expansion in its own lexical scope. Flattening repeated
// loop/helper bodies into Program scope makes same-named local DOM bindings
// overwrite one another during selector analysis.
return [block];
}
function inlineHelper(call: Node, ctx: ExpandCtx): Node[] {
@@ -20,6 +20,13 @@ describe("editabilityForProvenance", () => {
const start = (a: { resolvedStart?: number }): number | undefined => a.resolvedStart;
function expectDistinctProxyIdentities(script: string): void {
const { animations } = parseGsapScriptAcorn(script);
expect(animations[0]?.targetIdentity).toBeDefined();
expect(animations[1]?.targetIdentity).toBeDefined();
expect(animations[0]?.targetIdentity).not.toBe(animations[1]?.targetIdentity);
}
describe("parseGsapScriptAcorn — computed timelines", () => {
it("resolves an add-to-basket helper called twice (the reported case)", () => {
const script = `
@@ -65,6 +72,140 @@ describe("parseGsapScriptAcorn — computed timelines", () => {
expect(animations.map((a) => a.provenance?.kind)).toEqual(["loop", "loop", "loop"]);
});
it("keeps DOM target bindings distinct across bounded loop iterations", () => {
const { animations } = parseGsapScriptAcorn(`
const tl = gsap.timeline();
for (let i = 0; i < 2; i++) {
const card = document.getElementById("caption-card-" + i);
tl.to(card, { opacity: 1, duration: 1 }, i * 0.5);
}
`);
expect(animations.map((animation) => animation.targetSelector)).toEqual([
"#caption-card-0",
"#caption-card-1",
]);
});
it("keeps var DOM target bindings visible outside ordinary blocks", () => {
const { animations } = parseGsapScriptAcorn(`
const tl = gsap.timeline();
if (true) {
var card = document.getElementById("caption-card");
}
tl.to(card, { opacity: 1, duration: 1 }, 0);
`);
expect(animations.map((animation) => animation.targetSelector)).toEqual(["#caption-card"]);
});
it("keeps an outer let DOM target binding after assignment inside a block", () => {
const { animations } = parseGsapScriptAcorn(`
const tl = gsap.timeline();
let card;
if (true) {
card = document.getElementById("caption-card");
}
tl.to(card, { opacity: 1, duration: 1 }, 0);
`);
expect(animations.map((animation) => animation.targetSelector)).toEqual(["#caption-card"]);
});
it("uses declaration-scoped identities for object proxy targets", () => {
expectDistinctProxyIdentities(`
const tl = gsap.timeline();
(() => {
const driver = { value: 0 };
tl.to(driver, { value: 1, duration: 1 }, 0);
})();
(() => {
const driver = { value: 0 };
tl.to(driver, { value: 1, duration: 1 }, 0);
})();
`);
});
it("withholds object proxy identity when the binding is reassigned", () => {
const { animations } = parseGsapScriptAcorn(`
const tl = gsap.timeline();
let driver = { value: 0 };
tl.to(driver, { value: 1, duration: 1 }, 0);
driver = { value: 0 };
tl.to(driver, { value: 1, duration: 1 }, 0);
`);
expect(animations.map((animation) => animation.targetIdentity)).toEqual([undefined, undefined]);
});
it("keeps helper-created object proxy instances distinct", () => {
expectDistinctProxyIdentities(`
const tl = gsap.timeline();
function addDriver(at) {
const driver = { value: 0 };
tl.to(driver, { value: 1, duration: 1 }, at);
}
addDriver(0);
addDriver(0.5);
`);
});
it("keeps helper-created object proxy instances distinct across nested blocks", () => {
expectDistinctProxyIdentities(`
const tl = gsap.timeline();
function addDriver(at) {
if (at >= 0) {
const driver = { value: 0 };
tl.to(driver, { value: 1, duration: 1 }, at);
}
}
addDriver(0);
addDriver(0.5);
`);
});
it("keeps helper-created var proxy instances distinct", () => {
expectDistinctProxyIdentities(`
const tl = gsap.timeline();
function addDriver(at) {
var driver = { value: 0 };
tl.to(driver, { value: 1, duration: 1 }, at);
}
addDriver(0);
addDriver(0.5);
`);
});
it("keeps one outer object proxy stable across helper calls", () => {
const { animations } = parseGsapScriptAcorn(`
const tl = gsap.timeline();
const driver = { value: 0 };
function animateDriver(at) {
tl.to(driver, { value: 1, duration: 1 }, at);
}
animateDriver(0);
animateDriver(0.5);
`);
expect(animations[0]?.targetIdentity).toBeDefined();
expect(animations[1]?.targetIdentity).toBe(animations[0]?.targetIdentity);
});
it("keeps parameter DOM target assignments visible outside nested blocks", () => {
const { animations } = parseGsapScriptAcorn(`
const tl = gsap.timeline();
function configure(card) {
if (true) {
card = document.getElementById("caption-card");
}
tl.to(card, { opacity: 1, duration: 1 }, 0);
}
configure(null);
`);
expect(animations.map((animation) => animation.targetSelector)).toEqual(["#caption-card"]);
});
it("leaves a literal-position composition unchanged (regression)", () => {
const { animations } = parseGsapScriptAcorn(`
const tl = gsap.timeline();
+166 -12
View File
@@ -39,6 +39,7 @@ const QUERY_METHODS = new Set(["querySelector", "querySelectorAll"]);
const ITERATION_METHODS = new Set(["forEach", "map"]);
const SCOPE_NODE_TYPES = new Set([
"Program",
"BlockStatement",
"FunctionDeclaration",
"FunctionExpression",
"ArrowFunctionExpression",
@@ -50,6 +51,19 @@ type ScopeBindings = ReadonlyMap<string, number | string | boolean>;
/** Per-scope element bindings: scopeNode → (variable name → selector). */
type TargetBindings = Map<any, Map<string, string>>;
type IdentifierDeclaration = {
node: any;
scopeNode: any;
expandedScopeNode?: any;
name: string;
kind: "const" | "let" | "var" | "param";
};
type IdentifierBindingIndex = {
declarationsByName: Map<string, IdentifierDeclaration[]>;
reassignedDeclarations: Set<any>;
};
/**
* Side-table of top-level const/let ARRAY and OBJECT literals (of literals),
* captured by `collectScopeBindings` and stashed on the scope Map so that
@@ -226,10 +240,16 @@ function selectorFromQueryCall(node: any, scope: ScopeBindings): string | null {
* Return the nearest ancestor node whose type is in SCOPE_NODE_TYPES.
* `ancestors` is the acorn-walk ancestor array (root→current, current is last).
*/
function enclosingScopeNodeFromAncestors(ancestors: any[]): any {
function enclosingScopeNodeFromAncestors(ancestors: any[], includeBlocks = true): any {
for (let i = ancestors.length - 2; i >= 0; i--) {
const node = ancestors[i];
if (node && SCOPE_NODE_TYPES.has(node.type)) return node;
if (
node &&
SCOPE_NODE_TYPES.has(node.type) &&
(includeBlocks || node.type !== "BlockStatement")
) {
return node;
}
}
return null;
}
@@ -244,6 +264,82 @@ function scopeChainFromAncestors(ancestors: any[]): any[] {
return chain;
}
function nearestExpandedScopeFromAncestors(ancestors: any[]): any | undefined {
for (let index = ancestors.length - 2; index >= 0; index--) {
const candidate = ancestors[index];
if (candidate?.type === "BlockStatement" && readProvenance(candidate)) return candidate;
}
return undefined;
}
function findVisibleIdentifierDeclaration(
name: string,
ancestors: any[],
index: IdentifierBindingIndex,
usageStart = Number.POSITIVE_INFINITY,
): IdentifierDeclaration | undefined {
const declarations = index.declarationsByName.get(name) ?? [];
const expandedScopeNode = nearestExpandedScopeFromAncestors(ancestors);
for (const scopeNode of scopeChainFromAncestors(ancestors)) {
const candidates = declarations
.filter(
(declaration) =>
declaration.scopeNode === scopeNode &&
(!declaration.expandedScopeNode || declaration.expandedScopeNode === expandedScopeNode) &&
(declaration.kind === "var" ||
declaration.kind === "param" ||
declaration.node.start < usageStart),
)
.sort((left, right) => right.node.start - left.node.start);
if (candidates[0]) return candidates[0];
}
return undefined;
}
function collectIdentifierBindingIndex(ast: any): IdentifierBindingIndex {
const declarationsByName = new Map<string, IdentifierDeclaration[]>();
const reassignedDeclarations = new Set<any>();
acornWalk.ancestor(ast, {
VariableDeclarator(node: any, _: unknown, ancestors: any[]) {
const name = node.id?.name;
if (!name) return;
const declaration = ancestors.at(-2);
const kind = declaration?.kind as "const" | "let" | "var" | undefined;
if (!kind) return;
const includeBlocks = declaration?.type !== "VariableDeclaration" || kind !== "var";
const scopeNode = enclosingScopeNodeFromAncestors(ancestors, includeBlocks);
const expandedScopeNode = nearestExpandedScopeFromAncestors(ancestors);
const entries = declarationsByName.get(name) ?? [];
entries.push({ node, scopeNode, expandedScopeNode, name, kind });
declarationsByName.set(name, entries);
},
FunctionDeclaration: indexFunctionParameters,
FunctionExpression: indexFunctionParameters,
ArrowFunctionExpression: indexFunctionParameters,
} as any);
const index = { declarationsByName, reassignedDeclarations };
acornWalk.ancestor(ast, {
AssignmentExpression(node: any, _: unknown, ancestors: any[]) {
const name = node.left?.type === "Identifier" ? node.left.name : undefined;
if (!name) return;
const declaration = findVisibleIdentifierDeclaration(name, ancestors, index, node.start);
if (declaration) reassignedDeclarations.add(declaration.node);
},
} as any);
return index;
function indexFunctionParameters(node: any): void {
for (const parameter of node.params ?? []) {
if (parameter?.type !== "Identifier") continue;
const entries = declarationsByName.get(parameter.name) ?? [];
entries.push({ node: parameter, scopeNode: node, name: parameter.name, kind: "param" });
declarationsByName.set(parameter.name, entries);
}
}
}
// ── Target bindings ───────────────────────────────────────────────────────────
function addBinding(
@@ -334,7 +430,11 @@ function collectScopeBindings(ast: any): ScopeBindings {
* Pass 1: direct DOM-lookup assignments.
* Pass 2: forEach/map callback params whose collection's selector is known.
*/
function collectTargetBindings(ast: any, scope: ScopeBindings): TargetBindings {
function collectTargetBindings(
ast: any,
scope: ScopeBindings,
identifierBindings: IdentifierBindingIndex,
): TargetBindings {
const bindings: TargetBindings = new Map();
acornWalk.ancestor(ast, {
@@ -342,14 +442,35 @@ function collectTargetBindings(ast: any, scope: ScopeBindings): TargetBindings {
const name = node.id?.name;
const selector = selectorFromQueryCall(node.init, scope);
if (name && selector !== null) {
addBinding(bindings, enclosingScopeNodeFromAncestors(ancestors), name, selector);
const declaration = ancestors.at(-2);
const includeBlocks =
declaration?.type !== "VariableDeclaration" || declaration.kind !== "var";
addBinding(
bindings,
enclosingScopeNodeFromAncestors(ancestors, includeBlocks),
name,
selector,
);
}
},
AssignmentExpression(node: any, _: unknown, ancestors: any[]) {
const left = node.left;
const selector = selectorFromQueryCall(node.right, scope);
if (left?.type === "Identifier" && selector !== null) {
addBinding(bindings, enclosingScopeNodeFromAncestors(ancestors), left.name, selector);
const declaration = findVisibleIdentifierDeclaration(
left.name,
ancestors,
identifierBindings,
node.start,
);
addBinding(
bindings,
declaration?.scopeNode ??
nearestExpandedScopeFromAncestors(ancestors) ??
enclosingScopeNodeFromAncestors(ancestors),
left.name,
selector,
);
}
},
} as any);
@@ -1101,7 +1222,9 @@ function tweenCallToAnimation(
call: TweenCallInfo,
scope: ScopeBindings,
source: string,
identifierBindings: IdentifierBindingIndex,
): Omit<GsapAnimation, "id"> {
const provenance = readProvenance(call.node);
const vars = objectExpressionToRecord(call.varsArg, scope, source);
const properties: Record<string, number | string> = {};
const extras: Record<string, unknown> = {};
@@ -1201,9 +1324,34 @@ function tweenCallToAnimation(
// Relabel object-proxy / empty-target tweens so they don't read as bare
// __unresolved__: a dwell/hold spacer or an onUpdate-driven DOM channel (#5/#11).
let selector = call.selector;
let targetIdentity: string | undefined;
if (selector === "__unresolved__") {
const proxyLabel = describeProxyTarget(call.node.arguments?.[0], call.varsArg, scope);
if (proxyLabel) selector = proxyLabel;
const targetNode = call.node.arguments?.[0];
const proxyLabel = describeProxyTarget(targetNode, call.varsArg, scope);
if (proxyLabel) {
selector = proxyLabel;
if (targetNode?.type === "Identifier") {
const declaration = findVisibleIdentifierDeclaration(
targetNode.name,
call.ancestors,
identifierBindings,
call.node.start,
);
if (
declaration?.node.init?.type === "ObjectExpression" &&
!identifierBindings.reassignedDeclarations.has(declaration.node)
) {
const declarationProvenance =
readProvenance(declaration.scopeNode) ?? readProvenance(declaration.expandedScopeNode);
const instanceIdentity =
declarationProvenance &&
(declarationProvenance.kind === "helper" || declarationProvenance.kind === "loop")
? `:${declarationProvenance.kind}:${declarationProvenance.callSite ?? ""}:${declarationProvenance.iteration ?? ""}`
: "";
targetIdentity = `proxy:${targetNode.name}@${declaration.node.start}${instanceIdentity}`;
}
}
}
}
const anim: Omit<GsapAnimation, "id"> = {
@@ -1215,6 +1363,7 @@ function tweenCallToAnimation(
duration,
ease,
};
if (targetIdentity) anim.targetIdentity = targetIdentity;
if (!hasPositionArg) anim.implicitPosition = true;
let group = classifyTweenPropertyGroup(properties);
if (!group && keyframesData) {
@@ -1231,7 +1380,6 @@ function tweenCallToAnimation(
if (motionPathResult) anim.arcPath = motionPathResult.arcPath;
if (hasUnresolvedKeyframes) anim.hasUnresolvedKeyframes = true;
if (selector === "__unresolved__") anim.hasUnresolvedSelector = true;
const provenance = readProvenance(call.node);
if (provenance) anim.provenance = provenance;
return anim;
}
@@ -1670,13 +1818,16 @@ export function parseGsapScriptAcornForWrite(script: string): ParsedGsapAcornFor
locations: true,
});
const scope = collectScopeBindings(ast);
const targetBindings = collectTargetBindings(ast, scope);
const identifierBindings = collectIdentifierBindingIndex(ast);
const targetBindings = collectTargetBindings(ast, scope, identifierBindings);
const detection = findTimelineVar(ast, scope);
const ref: TimelineRef = detection.ref ?? { kind: "identifier", name: "tl" };
const timelineVar = timelineRootSource(ref, script);
const calls = findAllTweenCalls(ast, ref, scope, targetBindings);
sortBySourcePosition(calls);
const rawAnims = calls.map((call) => tweenCallToAnimation(call, scope, script));
const rawAnims = calls.map((call) =>
tweenCallToAnimation(call, scope, script, identifierBindings),
);
applyTimelineDefaults(rawAnims, detection.defaults);
resolveTimelinePositions(rawAnims);
const animations = assignStableIds(rawAnims);
@@ -1720,10 +1871,13 @@ export function parseGsapScriptAcorn(script: string): ParsedGsap {
/* fall back to current behavior */
}
}
const targetBindings = collectTargetBindings(ast, scope);
const identifierBindings = collectIdentifierBindingIndex(ast);
const targetBindings = collectTargetBindings(ast, scope, identifierBindings);
const calls = findAllTweenCalls(ast, ref, scope, targetBindings);
sortBySourcePosition(calls);
const rawAnims = calls.map((call) => tweenCallToAnimation(call, scope, script));
const rawAnims = calls.map((call) =>
tweenCallToAnimation(call, scope, script, identifierBindings),
);
applyTimelineDefaults(rawAnims, detection.defaults);
// Seed tween start-keyframes from gsap.set()/tl.set() pre-states (read-only
// enrichment; the write path keeps source untouched for round-trip parity).
+2
View File
@@ -50,6 +50,8 @@ export function editabilityForProvenance(provenance?: GsapProvenance): KeyframeE
export interface GsapAnimation {
id: string;
targetSelector: string;
/** Stable parser-only identity for non-DOM targets whose display label is not unique. */
targetIdentity?: string;
method: GsapMethod;
position: number | string;
properties: Record<string, number | string>;