mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
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:
@@ -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() {},
|
||||
|
||||
@@ -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="main">
|
||||
</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>
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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="c1" 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>
|
||||
|
||||
@@ -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.',
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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>;
|
||||
|
||||
Reference in New Issue
Block a user