Skip to content

Commit 0d874ad

Browse files
fix(skills): count proxy-driver tweens in the animation map (#3301)
enumerateTweens dropped every tween whose targets() held no Element: if (!targets.length) return; That silently deleted the proxy-driver idiom — tween a plain object, apply the motion inside onUpdate — which is real, visible animation. The consequence was not just a missing row: computeDensity counted zero active tweens across the tween's span, so findDeadZones reported animating time as DEAD, telling agents to add motion to a stretch that already had it. A target-less tween is now kept when a driver reaches it, marked driver:"onUpdate". The driver can be the tween's own onUpdate, or the TIMELINE's — the WebGL/uniform idiom is gsap.timeline({ onUpdate: renderFrame }) over children that tween plain uniform objects and carry no onUpdate of their own, so walk() threads a `driven` flag beside parentOffset. The discriminator is what keeps this from trading one false reading for another. A bare `tl.to({}, { duration: D })` spacer produces nothing, and every preset caption skin ends with exactly such a full-span anchor; counting those would mask genuine dead zones. So a tween's own onUpdate is proof of work by itself (a repaint loop need not animate a property), while an inherited driver additionally requires the tween to change something. There is no element to select or measure for a driver tween: * selectorHint is null rather than a placeholder — it feeds document.querySelector, so it must be absent, not unmatchable; * bbox sampling is skipped; the report shows "(onUpdate driver)"; * computeFlags guards its geometry flags on bboxes.length, since [].every() is vacuously true and would report an unmeasured tween as both degenerate and invisible; * describeTween says the motion is applied in JS and no geometry was measured; * the per-element analyses (buildElementLifecycles, detectStaggers) run over element-backed tweens only, so drivers cannot collapse into one pseudo- element or invent a stagger. Density, dead zones and the timeline still count them — those are per-span, which is what a driver has. Verified end to end: a 4s composition with an element tween over 0-1s and a proxy driver over 2-4s went from "1/1 tweens, dead zones: 1.5-4s" to "2/2 tweens" with no dead zone.
1 parent a41da86 commit 0d874ad

3 files changed

Lines changed: 215 additions & 12 deletions

File tree

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
"files": 17
2323
},
2424
"hyperframes-animation": {
25-
"hash": "2ce5ca7dbf361e27",
25+
"hash": "4418a24093c4b1c1",
2626
"files": 121
2727
},
2828
"hyperframes-audio": {

‎skills/hyperframes-animation/scripts/animation-map.mjs‎

Lines changed: 58 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,11 @@ try {
104104
(_, k) => +(tw.start + ((k + 0.5) / FRAMES) * (tw.end - tw.start)).toFixed(3),
105105
);
106106

107-
const bboxes = await sampleTweenBboxes(session.page, tw.selectorHint, times);
107+
// No selector means no element to measure (an onUpdate driver). Sampling anyway
108+
// would hand querySelector an unmatchable string.
109+
const bboxes = tw.selectorHint
110+
? await sampleTweenBboxes(session.page, tw.selectorHint, times)
111+
: [];
108112

109113
const animProps = tw.props.filter(
110114
(p) => !["parent", "overwrite", "immediateRender", "startAt", "runBackwards"].includes(p),
@@ -114,7 +118,8 @@ try {
114118

115119
report.tweens.push({
116120
index: i + 1,
117-
selector: tw.selectorHint,
121+
selector: tw.selectorHint ?? "(onUpdate driver)",
122+
driver: tw.driver,
118123
targets: tw.targetCount,
119124
props: animProps,
120125
start: +tw.start.toFixed(3),
@@ -138,8 +143,14 @@ try {
138143
// ── Composition-level analysis ──
139144
report.choreography = buildTimeline(report.tweens, duration);
140145
report.density = computeDensity(report.tweens, duration);
141-
report.staggers = detectStaggers(report.tweens);
142-
report.elements = buildElementLifecycles(report.tweens);
146+
// Staggers and lifecycles are per-ELEMENT, and a driver tween has none. Keyed on
147+
// tw.selector they would collapse every driver in the composition into one
148+
// "(onUpdate driver)" pseudo-element with null geometry, and let three same-duration
149+
// drivers read as a stagger no element performs. Density, dead zones and the timeline
150+
// still count them — those are per-SPAN, which is what a driver does have.
151+
const elementTweens = report.tweens.filter((tw) => tw.driver !== "onUpdate");
152+
report.staggers = detectStaggers(elementTweens);
153+
report.elements = buildElementLifecycles(elementTweens);
143154
report.deadZones = findDeadZones(report.density, duration);
144155
report.snapshots = await captureSnapshots(session, report.tweens, duration);
145156

@@ -184,17 +195,21 @@ async function enumerateTweens(session) {
184195
return cls ? `${el.tagName.toLowerCase()}.${cls}` : el.tagName.toLowerCase();
185196
};
186197

187-
const walk = (node, parentOffset = 0) => {
198+
const walk = (node, parentOffset = 0, parentDriven = false) => {
188199
if (!node) return;
189200
if (typeof node.getChildren === "function") {
190201
const offset = parentOffset + (node.startTime?.() ?? 0);
202+
// A TIMELINE can own the driver instead of the tween. The WebGL/uniform idiom is
203+
// gsap.timeline({ onUpdate: renderFrame }) over children that tween plain uniform
204+
// objects; those children carry no onUpdate of their own, so the driver has to
205+
// reach them from above or their motion reads as a dead zone all the same.
206+
const driven = parentDriven || typeof node.vars?.onUpdate === "function";
191207
for (const child of node.getChildren(true, true, true)) {
192-
walk(child, offset);
208+
walk(child, offset, driven);
193209
}
194210
return;
195211
}
196212
const targets = (node.targets?.() ?? []).filter((t) => t instanceof Element);
197-
if (!targets.length) return;
198213
const vars = node.vars ?? {};
199214
const props = Object.keys(vars).filter(
200215
(k) =>
@@ -210,10 +225,28 @@ async function enumerateTweens(session) {
210225
"stagger",
211226
].includes(k),
212227
);
228+
// The proxy-driver idiom tweens a plain object and applies the motion in onUpdate,
229+
// so targets() holds no Element. Dropping those tweens hid real motion from the
230+
// map: computeDensity saw zero active tweens over their span and findDeadZones
231+
// reported it as dead. There is no element to select or measure here, but the span
232+
// is real, so keep the tween and mark why it carries no geometry.
233+
//
234+
// Under an inherited driver the tween must also CHANGE something. Its own onUpdate is
235+
// proof of work by itself (a repaint loop need not animate a property), but a parent's
236+
// is not: a bare `tl.to({}, { duration: D })` spacer inside a driven timeline advances
237+
// the playhead without altering any value, so counting it would mask a genuine dead
238+
// zone — the exact false positive the tween-local rule was careful to avoid.
239+
const isProxyDriver =
240+
targets.length === 0 &&
241+
(typeof vars.onUpdate === "function" || (parentDriven && props.length > 0));
242+
if (!targets.length && !isProxyDriver) return;
213243
const start = parentOffset + (node.startTime?.() ?? 0);
214244
const end = start + (node.duration?.() ?? 0);
215245
results.push({
216-
selectorHint: selectorOf(targets[0]) ?? "(unknown)",
246+
// null, not a placeholder string: this feeds document.querySelector downstream,
247+
// so it must be absent rather than unmatchable.
248+
selectorHint: isProxyDriver ? null : (selectorOf(targets[0]) ?? "(unknown)"),
249+
driver: isProxyDriver ? "onUpdate" : "target",
217250
targetCount: targets.length,
218251
props,
219252
start,
@@ -234,7 +267,15 @@ function describeTween(tw, props, bboxes, flags) {
234267
const dur = (tw.end - tw.start).toFixed(2);
235268
const parts = [];
236269

237-
parts.push(`${tw.selectorHint} animates ${props.join("+")} over ${dur}s (${tw.ease})`);
270+
if (tw.selectorHint) {
271+
parts.push(`${tw.selectorHint} animates ${props.join("+")} over ${dur}s (${tw.ease})`);
272+
} else {
273+
// An onUpdate driver: the span and props are known, the affected element is not.
274+
parts.push(
275+
`an onUpdate driver animates ${props.join("+")} over ${dur}s (${tw.ease}) — ` +
276+
`motion is applied in JS, so no element geometry was measured`,
277+
);
278+
}
238279

239280
// Movement
240281
const first = bboxes[0];
@@ -299,7 +340,10 @@ function computeFlags(tw, bboxes, { width, height }) {
299340
const flags = [];
300341
const dur = tw.end - tw.start;
301342

302-
if (bboxes.every((b) => b.w === 0 || b.h === 0)) flags.push("degenerate");
343+
// No samples at all (an onUpdate driver has no element to measure) is not evidence of
344+
// a degenerate or invisible box — `[].every()` is vacuously true, so guard the
345+
// geometry-derived flags. The pacing flags below read only start/end and still apply.
346+
if (bboxes.length && bboxes.every((b) => b.w === 0 || b.h === 0)) flags.push("degenerate");
303347

304348
const anyOffscreen = bboxes.some(
305349
(b) =>
@@ -314,7 +358,10 @@ function computeFlags(tw, bboxes, { width, height }) {
314358
);
315359
if (anyOffscreen) flags.push("offscreen");
316360

317-
if (bboxes.every((b) => b.opacity !== undefined && b.opacity < 0.01 && b.visible)) {
361+
if (
362+
bboxes.length &&
363+
bboxes.every((b) => b.opacity !== undefined && b.opacity < 0.01 && b.visible)
364+
) {
318365
flags.push("invisible");
319366
}
320367

‎skills/hyperframes-animation/scripts/animation-map.test.mjs‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,3 +286,159 @@ describe("transient-init retry", () => {
286286
}
287287
});
288288
});
289+
290+
// ── Proxy-driver tweens (the false dead-zone fix) ───────────────────────────
291+
// The proxy-driver idiom tweens a plain object and applies the motion inside
292+
// onUpdate, so the tween's targets() holds no Element. The map used to drop those
293+
// tweens outright, which meant computeDensity counted zero active tweens over their
294+
// span and findDeadZones reported real motion as a dead zone.
295+
//
296+
// The fake producer hands animation-map a session whose page.evaluate runs the
297+
// callback in this process, against a stubbed window/document. That exercises the real
298+
// enumerateTweens/computeDensity/findDeadZones code without a browser.
299+
const FAKE_PROXY_DRIVER_ENV = [
300+
"globalThis.Element = class Element {};",
301+
"const mover = new globalThis.Element();",
302+
'mover.id = "mover";',
303+
"mover.classList = [];",
304+
// 0-1s: an ordinary element tween.
305+
"const elementTween = {",
306+
" targets: () => [mover],",
307+
' vars: { x: 900, duration: 1, ease: "power2.out" },',
308+
" startTime: () => 0,",
309+
" duration: () => 1,",
310+
"};",
311+
// 2-4s: a proxy driver. Real motion, no Element target.
312+
"const proxyTween = {",
313+
" targets: () => [{ v: 0 }],",
314+
' vars: { v: 100, duration: 2, ease: "none", onUpdate() {} },',
315+
" startTime: () => 2,",
316+
" duration: () => 2,",
317+
"};",
318+
// 2-4s as well: a bare spacer with no onUpdate. Produces nothing, must stay dropped,
319+
// otherwise every full-span anchor tween would mask genuine dead zones.
320+
"const spacerTween = {",
321+
" targets: () => [{}],",
322+
" vars: { duration: 2 },",
323+
" startTime: () => 2,",
324+
" duration: () => 2,",
325+
"};",
326+
"const timeline = {",
327+
" getChildren: () => [elementTween, proxyTween, spacerTween],",
328+
" startTime: () => 0,",
329+
" duration: () => 4,",
330+
" seek() {},",
331+
"};",
332+
"globalThis.window = { __timelines: { main: timeline } };",
333+
"globalThis.document = { querySelector: () => null, querySelectorAll: () => [] };",
334+
"globalThis.getComputedStyle = () => ({",
335+
' opacity: "1",',
336+
' visibility: "visible",',
337+
' display: "block",',
338+
"});",
339+
'export async function createFileServer() { return { url: "http://test", close() {} }; }',
340+
"export async function createCaptureSession() {",
341+
" return { page: { evaluate: async (fn, arg) => fn(arg) } };",
342+
"}",
343+
"export async function closeCaptureSession() {}",
344+
"export async function initializeSession() {}",
345+
"export async function getCompositionDuration() { return 4; }",
346+
].join("\n");
347+
348+
// The WebGL/uniform shape, e.g. skills/music-to-video/references/templates/
349+
// held-message-living-field: the TIMELINE carries onUpdate: renderFrame and its children
350+
// tween plain uniform objects. No child has an onUpdate of its own, so a tween-local
351+
// discriminator misses all of them and the whole composition reads as one dead zone.
352+
const FAKE_PARENT_DRIVER_ENV = [
353+
"globalThis.Element = class Element {};",
354+
"const uniformTween = {",
355+
" targets: () => [{ value: 0 }],",
356+
' vars: { value: 12, duration: 12, ease: "none" },',
357+
" startTime: () => 0,",
358+
" duration: () => 12,",
359+
"};",
360+
// Same driven timeline, but this one alters nothing — the repaint it triggers is
361+
// identical frame to frame, so it must NOT count as motion.
362+
"const spacerTween = {",
363+
" targets: () => [{}],",
364+
" vars: { duration: 12 },",
365+
" startTime: () => 0,",
366+
" duration: () => 12,",
367+
"};",
368+
"const timeline = {",
369+
" vars: { onUpdate() {} },",
370+
" getChildren: () => [uniformTween, spacerTween],",
371+
" startTime: () => 0,",
372+
" duration: () => 12,",
373+
" seek() {},",
374+
"};",
375+
"globalThis.window = { __timelines: { main: timeline } };",
376+
"globalThis.document = { querySelector: () => null, querySelectorAll: () => [] };",
377+
"globalThis.getComputedStyle = () => ({",
378+
' opacity: "1",',
379+
' visibility: "visible",',
380+
' display: "block",',
381+
"});",
382+
'export async function createFileServer() { return { url: "http://test", close() {} }; }',
383+
"export async function createCaptureSession() {",
384+
" return { page: { evaluate: async (fn, arg) => fn(arg) } };",
385+
"}",
386+
"export async function closeCaptureSession() {}",
387+
"export async function initializeSession() {}",
388+
"export async function getCompositionDuration() { return 12; }",
389+
].join("\n");
390+
391+
describe("proxy-driver tweens", () => {
392+
it("counts an onUpdate driver's span instead of reporting it as a dead zone", () => {
393+
const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-proxy-test-"));
394+
try {
395+
const compositionDir = writeFakeEnv(root, FAKE_PROXY_DRIVER_ENV);
396+
const output = runHelper(HELPERS[0], root, compositionDir);
397+
const report = JSON.parse(readFileSync(join(root, "out", "animation-map.json"), "utf8"));
398+
399+
const drivers = report.tweens.filter((tw) => tw.driver === "onUpdate");
400+
assert.equal(drivers.length, 1, `expected one onUpdate driver in:\n${output}`);
401+
assert.equal(drivers[0].start, 2);
402+
assert.equal(drivers[0].end, 4);
403+
assert.equal(drivers[0].targets, 0);
404+
assert.deepEqual(drivers[0].bboxes, [], "there is no element to measure");
405+
// `[].every()` is vacuously true, so unmeasured must not read as degenerate/invisible.
406+
assert.deepEqual(drivers[0].flags, []);
407+
408+
assert.deepEqual(report.deadZones, [], "2-4s is animating, not dead");
409+
// The bare spacer stays out — only the element tween and the driver are mapped.
410+
assert.equal(report.tweens.length, 2);
411+
412+
// Per-ELEMENT analyses must not adopt the driver as a pseudo-element.
413+
assert.deepEqual(Object.keys(report.elements), ["#mover"]);
414+
assert.deepEqual(report.staggers, []);
415+
} finally {
416+
rmSync(root, { recursive: true, force: true });
417+
}
418+
});
419+
420+
it("inherits a driver the TIMELINE owns, without counting a spacer under it", () => {
421+
const root = mkdtempSync(join(tmpdir(), "hyperframes-skill-parent-driver-test-"));
422+
try {
423+
const compositionDir = writeFakeEnv(root, FAKE_PARENT_DRIVER_ENV);
424+
const output = runHelper(HELPERS[0], root, compositionDir);
425+
const report = JSON.parse(readFileSync(join(root, "out", "animation-map.json"), "utf8"));
426+
427+
const drivers = report.tweens.filter((tw) => tw.driver === "onUpdate");
428+
assert.equal(drivers.length, 1, `expected one inherited driver in:\n${output}`);
429+
assert.deepEqual(drivers[0].props, ["value"]);
430+
assert.equal(drivers[0].start, 0);
431+
assert.equal(drivers[0].end, 12);
432+
433+
assert.deepEqual(report.deadZones, [], "the uniform tween animates the whole span");
434+
// Nothing element-backed here at all, so both per-element analyses stay empty.
435+
assert.deepEqual(report.elements, {});
436+
assert.deepEqual(report.staggers, []);
437+
// The spacer changes no value, so the parent's onUpdate repaints an identical frame.
438+
// Counting it would mask a real dead zone.
439+
assert.equal(report.tweens.length, 1);
440+
} finally {
441+
rmSync(root, { recursive: true, force: true });
442+
}
443+
});
444+
});

0 commit comments

Comments
 (0)