Skip to content

Commit 3ef76ea

Browse files
fix(core): warn on GSAP boundary exits without hard kill (heygen-com#474)
Fixes heygen-com#473. ## Problem The HyperFrames skill now tells agents to add deterministic `tl.set()` hard-kills after elements fade out at beat / scene boundaries, but the linter did not enforce that rule outside the narrow caption-specific check. That made the rule easy for sub-agents to ignore: an element could fade to `opacity: 0` exactly as the next clip starts, with no explicit hidden-state set at the boundary. During non-linear seeking or frame capture, that leaves the final visibility state dependent on tween interpolation instead of an authored deterministic kill. ## What this fixes This PR adds a generalized GSAP lint warning for scene-boundary exits: - detects GSAP `to` / `fromTo` exit tweens that end at or near a clip `data-start` boundary - treats `opacity: 0`, `autoAlpha: 0`, `visibility: "hidden"`, and `display: "none"` as hidden exit states - requires a matching same-selector `tl.set(...)` hidden state at the same boundary - scopes clip-boundary matching to the timeline's registered composition so sub-composition exits do not match unrelated root boundaries - reports `gsap_exit_missing_hard_kill` with the selector, boundary time, source snippet, and a fix hint that preserves the authored hidden property when possible - keeps valid compositions quiet when the boundary hard-kill already exists ## Why Clip boundaries are the exact points where rendered frames are most sensitive to stale DOM state. A fade-out tween describes a transition, but it does not give the linter or the authoring model an explicit deterministic state to land on when seeking around the boundary. The existing caption rule proved the class of bug was worth catching, but it only applied to caption-loop patterns. The issue in heygen-com#473 is broader: any element inside a timed composition can exit at a scene boundary and need the same deterministic cleanup. ## Root cause The GSAP lint rule parser already calculated tween windows and clip metadata existed in the lint context, but no rule connected those two facts: - clip `data-start` values were not used as scene-boundary checkpoints for GSAP exits - parsed GSAP windows tracked property names, but not enough property values to tell whether a tween ended in a hidden state - hard-kill detection only existed as a caption-specific regex, so normal scene elements were missed This PR extends the existing GSAP window metadata with parsed property values, then checks hidden-state exits against same-composition clip start boundaries and same-selector `tl.set` calls. ## Verification ### Local checks - `bun run --filter @hyperframes/core test src/lint/rules/gsap.test.ts` - `bunx oxlint packages/core/src/lint/rules/gsap.ts packages/core/src/lint/rules/gsap.test.ts` - `bunx oxfmt --check packages/core/src/lint/rules/gsap.ts packages/core/src/lint/rules/gsap.test.ts` - `bun run --filter @hyperframes/core typecheck` - `bun run --filter @hyperframes/core test` - `bun run --filter @hyperframes/core build` ### CLI verification Verified against local fixtures where `#headline` exits at the next clip boundary without a hard kill: - opacity fixture reports `gsap_exit_missing_hard_kill` for `#headline` at `3.00s` - autoAlpha fixture reports the same warning and suggests `tl.set("#headline", { autoAlpha: 0 }, 3.00)` - sub-composition regression test confirms a `sub` timeline exit no longer matches an unrelated root composition boundary ### Browser verification Verified the Studio lint flow with `agent-browser` against the autoAlpha fixture: - opened Studio at `http://127.0.0.1:43174/#project/issue-473-autoalpha` - clicked the real `Lint` button - confirmed the lint modal shows the new warning and the property-preserving `{ autoAlpha: 0 }` fix hint - saved local proof artifacts under `qa-artifacts/issue-473/` ## Notes - the `tmp/issue-473-*` fixtures and `qa-artifacts/issue-473` browser proof are local-only and are not part of this PR - this intentionally stays heuristic-based: it warns near clip start boundaries instead of trying to build a full GSAP execution model - expression-valued GSAP props and deeper regex-parser limitations remain outside this PR's scope; those are parser-hardening work, not required for the bug in heygen-com#473
1 parent 0b41934 commit 3ef76ea

2 files changed

Lines changed: 271 additions & 3 deletions

File tree

‎packages/core/src/lint/rules/gsap.test.ts‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -608,6 +608,107 @@ describe("GSAP rules", () => {
608608
expect(finding).toBeUndefined();
609609
});
610610

611+
it("warns when an opacity exit ends at a clip start boundary without a hard kill", () => {
612+
const html = `
613+
<html><body>
614+
<div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
615+
<div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
616+
<h1 id="headline">First beat</h1>
617+
</div>
618+
<div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
619+
<h1>Second beat</h1>
620+
</div>
621+
</div>
622+
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
623+
<script>
624+
window.__timelines = window.__timelines || {};
625+
const tl = gsap.timeline({ paused: true });
626+
tl.to("#headline", { opacity: 0, duration: 0.3 }, 2.7);
627+
window.__timelines["c1"] = tl;
628+
</script>
629+
</body></html>`;
630+
const result = lintHyperframeHtml(html);
631+
const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
632+
expect(finding).toBeDefined();
633+
expect(finding?.severity).toBe("warning");
634+
expect(finding?.selector).toBe("#headline");
635+
expect(finding?.message).toContain("3.00s");
636+
});
637+
638+
it("does not warn when a boundary exit has a matching hard kill", () => {
639+
const html = `
640+
<html><body>
641+
<div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
642+
<div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
643+
<h1 id="headline">First beat</h1>
644+
</div>
645+
<div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
646+
<h1>Second beat</h1>
647+
</div>
648+
</div>
649+
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
650+
<script>
651+
window.__timelines = window.__timelines || {};
652+
const tl = gsap.timeline({ paused: true });
653+
tl.to("#headline", { opacity: 0, duration: 0.3 }, 2.7);
654+
tl.set("#headline", { opacity: 0, visibility: "hidden" }, 3);
655+
window.__timelines["c1"] = tl;
656+
</script>
657+
</body></html>`;
658+
const result = lintHyperframeHtml(html);
659+
const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
660+
expect(finding).toBeUndefined();
661+
});
662+
663+
it("does not match sub-composition exits against root clip boundaries", () => {
664+
const html = `
665+
<html><body>
666+
<div data-composition-id="root" data-width="1920" data-height="1080" data-start="0" data-duration="6">
667+
<div id="root-a" class="clip" data-start="0" data-duration="3" data-track-index="0"></div>
668+
<div id="root-b" class="clip" data-start="3" data-duration="3" data-track-index="0"></div>
669+
</div>
670+
<div data-composition-id="sub" data-width="1920" data-height="1080" data-start="0" data-duration="4">
671+
<div id="sub-a" class="clip" data-start="0" data-duration="2" data-track-index="0">
672+
<h1 id="sub-title">Sub scene</h1>
673+
</div>
674+
<div id="sub-b" class="clip" data-start="2" data-duration="2" data-track-index="0"></div>
675+
</div>
676+
<script>
677+
window.__timelines = window.__timelines || {};
678+
const tl = gsap.timeline({ paused: true });
679+
tl.to("#sub-title", { opacity: 0, duration: 0.3 }, 2.7);
680+
window.__timelines["sub"] = tl;
681+
</script>
682+
</body></html>`;
683+
const result = lintHyperframeHtml(html);
684+
const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
685+
expect(finding).toBeUndefined();
686+
});
687+
688+
it("uses the authored hidden property in hard-kill fix hints", () => {
689+
const html = `
690+
<html><body>
691+
<div data-composition-id="c1" data-width="1920" data-height="1080" data-start="0" data-duration="6">
692+
<div id="scene-a" class="clip" data-start="0" data-duration="3" data-track-index="0">
693+
<h1 id="headline">First beat</h1>
694+
</div>
695+
<div id="scene-b" class="clip" data-start="3" data-duration="3" data-track-index="0">
696+
<h1>Second beat</h1>
697+
</div>
698+
</div>
699+
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
700+
<script>
701+
window.__timelines = window.__timelines || {};
702+
const tl = gsap.timeline({ paused: true });
703+
tl.to("#headline", { autoAlpha: 0, duration: 0.3 }, 2.7);
704+
window.__timelines["c1"] = tl;
705+
</script>
706+
</body></html>`;
707+
const result = lintHyperframeHtml(html);
708+
const finding = result.findings.find((f) => f.code === "gsap_exit_missing_hard_kill");
709+
expect(finding?.fixHint).toContain("{ autoAlpha: 0 }");
710+
});
711+
611712
it("does not false-positive on repeat: -10 (invalid GSAP but not infinite)", () => {
612713
const html = `
613714
<html><body>

‎packages/core/src/lint/rules/gsap.ts‎

Lines changed: 170 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,20 @@ type GsapWindow = {
1010
position: number;
1111
end: number;
1212
properties: string[];
13+
propertyValues: Record<string, string | number>;
1314
overwriteAuto: boolean;
1415
method: string;
1516
raw: string;
1617
};
1718

19+
type CompositionRange = {
20+
id: string;
21+
start: number;
22+
end: number;
23+
};
24+
1825
const META_GSAP_KEYS = new Set(["duration", "ease", "repeat", "yoyo", "overwrite", "delay"]);
26+
const SCENE_BOUNDARY_EPSILON_SECONDS = 0.05;
1927

2028
// ── GSAP parsing utilities ─────────────────────────────────────────────────
2129

@@ -68,6 +76,7 @@ function extractGsapWindows(script: string): GsapWindow[] {
6876
position: animation.position,
6977
end: animation.position + meta.effectiveDuration,
7078
properties: meta.properties.length > 0 ? meta.properties : Object.keys(animation.properties),
79+
propertyValues: meta.propertyValues,
7180
overwriteAuto: meta.overwriteAuto,
7281
method: match[1] ?? "to",
7382
raw,
@@ -79,9 +88,20 @@ function extractGsapWindows(script: string): GsapWindow[] {
7988
function parseGsapWindowMeta(
8089
method: string,
8190
argsStr: string,
82-
): { effectiveDuration: number; properties: string[]; overwriteAuto: boolean } {
91+
): {
92+
effectiveDuration: number;
93+
properties: string[];
94+
propertyValues: Record<string, string | number>;
95+
overwriteAuto: boolean;
96+
} {
97+
const emptyMeta = {
98+
effectiveDuration: 0,
99+
properties: [],
100+
propertyValues: {},
101+
overwriteAuto: false,
102+
};
83103
const selectorMatch = argsStr.match(/^\s*["']([^"']+)["']\s*,/);
84-
if (!selectorMatch) return { effectiveDuration: 0, properties: [], overwriteAuto: false };
104+
if (!selectorMatch) return emptyMeta;
85105

86106
const afterSelector = argsStr.slice(selectorMatch[0].length);
87107
let properties: Record<string, string | number> = {};
@@ -124,6 +144,7 @@ function parseGsapWindowMeta(
124144
return {
125145
effectiveDuration: method === "set" ? 0 : effectiveDuration,
126146
properties: [...propertyNames],
147+
propertyValues: properties,
127148
overwriteAuto,
128149
};
129150
}
@@ -179,6 +200,123 @@ function stringValue(value: string | number | undefined): string | null {
179200
return null;
180201
}
181202

203+
function zeroValue(value: string | number | undefined): boolean {
204+
if (typeof value === "number") return value === 0;
205+
if (typeof value !== "string") return false;
206+
return Number(value.trim()) === 0;
207+
}
208+
209+
function isHiddenGsapState(values: Record<string, string | number>): boolean {
210+
const visibility = stringValue(values.visibility)?.toLowerCase();
211+
const display = stringValue(values.display)?.toLowerCase();
212+
return (
213+
zeroValue(values.opacity) ||
214+
zeroValue(values.autoAlpha) ||
215+
visibility === "hidden" ||
216+
display === "none"
217+
);
218+
}
219+
220+
function isSceneBoundaryExit(win: GsapWindow): boolean {
221+
if (win.end <= win.position) return false;
222+
if (win.method !== "to" && win.method !== "fromTo") return false;
223+
return isHiddenGsapState(win.propertyValues);
224+
}
225+
226+
function isHardKillSet(win: GsapWindow, selector: string, boundary: number): boolean {
227+
return (
228+
win.method === "set" &&
229+
win.targetSelector === selector &&
230+
Math.abs(win.position - boundary) <= SCENE_BOUNDARY_EPSILON_SECONDS &&
231+
isHiddenGsapState(win.propertyValues)
232+
);
233+
}
234+
235+
function hiddenStateLiteral(values: Record<string, string | number>): string {
236+
if (zeroValue(values.autoAlpha)) return "{ autoAlpha: 0 }";
237+
if (zeroValue(values.opacity)) return "{ opacity: 0 }";
238+
if (stringValue(values.visibility)?.toLowerCase() === "hidden") return '{ visibility: "hidden" }';
239+
if (stringValue(values.display)?.toLowerCase() === "none") return '{ display: "none" }';
240+
return "{ opacity: 0 }";
241+
}
242+
243+
function findTagEnd(source: string, tag: OpenTag): number {
244+
const escapedTagName = tag.name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
245+
const pattern = new RegExp(`<\\/?${escapedTagName}\\b[^>]*>`, "gi");
246+
pattern.lastIndex = tag.index;
247+
248+
let depth = 0;
249+
let match: RegExpExecArray | null;
250+
while ((match = pattern.exec(source)) !== null) {
251+
const raw = match[0];
252+
const isClosing = /^<\s*\//.test(raw);
253+
const isSelfClosing = /\/\s*>$/.test(raw);
254+
if (!isClosing && !isSelfClosing) depth += 1;
255+
if (isClosing) depth -= 1;
256+
if (depth === 0) return pattern.lastIndex;
257+
}
258+
259+
return source.length;
260+
}
261+
262+
function collectCompositionRanges(source: string, tags: OpenTag[]): CompositionRange[] {
263+
return tags
264+
.map((tag) => {
265+
const id = readAttr(tag.raw, "data-composition-id");
266+
if (!id) return null;
267+
return {
268+
id,
269+
start: tag.index,
270+
end: findTagEnd(source, tag),
271+
};
272+
})
273+
.filter((range) => range !== null);
274+
}
275+
276+
function findContainingCompositionId(tag: OpenTag, ranges: CompositionRange[]): string | null {
277+
let match: CompositionRange | null = null;
278+
for (const range of ranges) {
279+
if (tag.index < range.start || tag.index >= range.end) continue;
280+
if (!match || range.start >= match.start) match = range;
281+
}
282+
return match?.id || null;
283+
}
284+
285+
function collectClipStartBoundariesByComposition(
286+
source: string,
287+
tags: OpenTag[],
288+
): Map<string, number[]> {
289+
const ranges = collectCompositionRanges(source, tags);
290+
const boundaries = new Map<string, Set<number>>();
291+
292+
for (const tag of tags) {
293+
const classAttr = readAttr(tag.raw, "class") || "";
294+
const classes = classAttr.split(/\s+/).filter(Boolean);
295+
if (!classes.includes("clip")) continue;
296+
const compositionId = findContainingCompositionId(tag, ranges);
297+
if (!compositionId) continue;
298+
const start = numberValue(readAttr(tag.raw, "data-start") ?? undefined);
299+
if (start == null || start <= 0) continue;
300+
const compositionBoundaries = boundaries.get(compositionId) ?? new Set<number>();
301+
compositionBoundaries.add(start);
302+
boundaries.set(compositionId, compositionBoundaries);
303+
}
304+
305+
return new Map(
306+
[...boundaries.entries()].map(([compositionId, values]) => [
307+
compositionId,
308+
[...values].sort((a, b) => a - b),
309+
]),
310+
);
311+
}
312+
313+
function findMatchingSceneBoundary(time: number, boundaries: number[]): number | null {
314+
for (const boundary of boundaries) {
315+
if (Math.abs(time - boundary) <= SCENE_BOUNDARY_EPSILON_SECONDS) return boundary;
316+
}
317+
return null;
318+
}
319+
182320
function isSuspiciousGlobalSelector(selector: string): boolean {
183321
if (!selector) return false;
184322
if (selector.includes("[data-composition-id=")) return false;
@@ -233,7 +371,7 @@ function cssTransformToGsapProps(cssTransform: string): string | null {
233371

234372
export const gsapRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
235373
// overlapping_gsap_tweens + gsap_animates_clip_element + unscoped_gsap_selector
236-
({ tags, scripts, rootCompositionId }) => {
374+
({ source, tags, scripts, rootCompositionId }) => {
237375
const findings: HyperframeLintFinding[] = [];
238376

239377
// Build clip element selector map
@@ -257,10 +395,13 @@ export const gsapRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
257395
}
258396

259397
const classUsage = countClassUsage(tags);
398+
const clipStartBoundariesByComposition = collectClipStartBoundariesByComposition(source, tags);
260399

261400
for (const script of scripts) {
262401
const localTimelineCompId = readRegisteredTimelineCompositionId(script.content);
263402
const gsapWindows = extractGsapWindows(script.content);
403+
const clipStartBoundaries =
404+
clipStartBoundariesByComposition.get(localTimelineCompId || rootCompositionId || "") ?? [];
264405

265406
// overlapping_gsap_tweens
266407
for (let i = 0; i < gsapWindows.length; i++) {
@@ -291,6 +432,32 @@ export const gsapRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
291432
}
292433
}
293434

435+
// gsap_exit_missing_hard_kill
436+
if (clipStartBoundaries.length > 0) {
437+
for (const win of gsapWindows) {
438+
if (!isSceneBoundaryExit(win)) continue;
439+
const boundary = findMatchingSceneBoundary(win.end, clipStartBoundaries);
440+
if (boundary == null) continue;
441+
const hasHardKill = gsapWindows.some((candidate) =>
442+
isHardKillSet(candidate, win.targetSelector, boundary),
443+
);
444+
if (hasHardKill) continue;
445+
446+
findings.push({
447+
code: "gsap_exit_missing_hard_kill",
448+
severity: "warning",
449+
message:
450+
`GSAP exit on "${win.targetSelector}" ends at the ${boundary.toFixed(2)}s clip start boundary ` +
451+
"without a matching tl.set hard kill. Non-linear seeking can land after the fade and leave stale visibility state.",
452+
selector: win.targetSelector,
453+
fixHint:
454+
`Add \`tl.set("${win.targetSelector}", ${hiddenStateLiteral(win.propertyValues)}, ${boundary.toFixed(2)})\` ` +
455+
"after the exit tween.",
456+
snippet: truncateSnippet(win.raw),
457+
});
458+
}
459+
}
460+
294461
// gsap_animates_clip_element — only error when GSAP animates visibility/display
295462
for (const win of gsapWindows) {
296463
const sel = win.targetSelector;

0 commit comments

Comments
 (0)