Skip to content

Commit 344d9c0

Browse files
committed
fix: bound invalid render durations
1 parent 911b332 commit 344d9c0

13 files changed

Lines changed: 193 additions & 30 deletions

File tree

‎docs/guides/claude-design-hyperframes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -374,7 +374,7 @@ The skeleton handles most structural rules. These are the runtime rules the skel
374374
| `Math.random()` | Seeded PRNG (only if you need randomness) |
375375
| `Date.now()`, `performance.now()` | Hard-coded timing or `tl.time()` in `onUpdate` |
376376
| `setInterval`, `setTimeout` | Timeline tweens + `onUpdate` |
377-
| `repeat: -1` | `repeat: Math.ceil(duration / cycle) - 1` |
377+
| `repeat: -1` | `repeat: Math.max(0, Math.floor(duration / cycle) - 1)` |
378378
| `stagger: { from: "random" }` | `from: "start"`, `"center"`, `"end"` |
379379
| Async timeline construction | Synchronous at page load |
380380

‎docs/guides/claude-design-send-to-hyperframes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -371,7 +371,7 @@ The cloud renderer seeks the timeline frame-by-frame. Non-deterministic or self-
371371
| `Date.now()`, `performance.now()` | hard-coded timing or `tl.time()` in `onUpdate` |
372372
| `setInterval`, `setTimeout` | timeline tweens + `onUpdate` |
373373
| `requestAnimationFrame` | GSAP tweens |
374-
| `repeat: -1` | `repeat: Math.ceil(duration / cycle) - 1` |
374+
| `repeat: -1` | `repeat: Math.max(0, Math.floor(duration / cycle) - 1)` |
375375
| `stagger: { from: "random" }` | `from: "start"`, `"center"`, or `"end"` |
376376
| async timeline construction | build synchronously at page load |
377377
| `video.play()` / `audio.play()` | the framework owns playback |

‎packages/engine/src/services/frameCapture-staticDedupTimelineCall.test.ts‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
import { describe, it, expect, vi } from "vitest";
2-
import { computeStaticFrameSet } from "./frameCapture.js";
2+
import {
3+
computeStaticFrameSet,
4+
isStaticDedupFrameAnalysisSafe,
5+
MAX_STATIC_DEDUP_ANALYSIS_FRAMES,
6+
} from "./frameCapture.js";
37

48
/**
59
* Regression lock: a GSAP `tl.call()` disqualifies a composition from
@@ -65,4 +69,40 @@ describe("computeStaticFrameSet disqualifies a comp containing a tl.call()", ()
6569
expect(result.eligible).toBe(true);
6670
expect(result.staticFrameSet.size).toBeGreaterThan(0);
6771
});
72+
73+
it("fails closed before allocating frame Sets for a sentinel-sized duration", async () => {
74+
const page = {
75+
evaluate: vi.fn().mockResolvedValueOnce({
76+
intervals: [{ start: 0, end: 10_000_000_000 }],
77+
tweenCount: 1,
78+
duration: 10_000_000_000,
79+
hasVideo: false,
80+
hasCanvas: false,
81+
hasNonGsapAnim: false,
82+
hasUnresolvableClipStart: false,
83+
hasTimelineCall: false,
84+
}),
85+
} as unknown as Parameters<typeof computeStaticFrameSet>[0];
86+
87+
const result = await computeStaticFrameSet(page, 30);
88+
89+
expect(result.eligible).toBe(false);
90+
expect(result.reason).toContain("frame analysis limit");
91+
expect(result.staticFrameSet.size).toBe(0);
92+
// No clip-boundary scan: oversized metadata exits before frame-index work starts.
93+
expect(page.evaluate).toHaveBeenCalledTimes(1);
94+
});
95+
});
96+
97+
describe("static-dedup frame analysis cardinality", () => {
98+
it("accepts the configured boundary and rejects the next frame", () => {
99+
expect(isStaticDedupFrameAnalysisSafe(MAX_STATIC_DEDUP_ANALYSIS_FRAMES)).toBe(true);
100+
expect(isStaticDedupFrameAnalysisSafe(MAX_STATIC_DEDUP_ANALYSIS_FRAMES + 1)).toBe(false);
101+
});
102+
103+
it("rejects non-finite, unsafe, and non-positive frame counts", () => {
104+
expect(isStaticDedupFrameAnalysisSafe(Number.POSITIVE_INFINITY)).toBe(false);
105+
expect(isStaticDedupFrameAnalysisSafe(Number.MAX_SAFE_INTEGER + 1)).toBe(false);
106+
expect(isStaticDedupFrameAnalysisSafe(0)).toBe(false);
107+
});
68108
});

‎packages/engine/src/services/frameCapture.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2376,6 +2376,20 @@ async function computeClipBoundaryFrames(page: Page, fps: number): Promise<Set<n
23762376
return frames;
23772377
}
23782378

2379+
// Static dedup is an optional optimization. Building frame-index Sets scales with the
2380+
// composition's declared duration, so malformed/sentinel durations must fail closed before
2381+
// allocating them. Normal capture and the producer's typed duration validation still proceed.
2382+
export const MAX_STATIC_DEDUP_ANALYSIS_FRAMES = 1_000_000;
2383+
2384+
export function isStaticDedupFrameAnalysisSafe(totalFrames: number): boolean {
2385+
return (
2386+
Number.isFinite(totalFrames) &&
2387+
Number.isSafeInteger(totalFrames) &&
2388+
totalFrames > 0 &&
2389+
totalFrames <= MAX_STATIC_DEDUP_ANALYSIS_FRAMES
2390+
);
2391+
}
2392+
23792393
/**
23802394
* Predict the dedupable (static) frame set from window.__timelines. A frame f (f>0) is
23812395
* static iff NEITHER f NOR f-1 falls inside any GSAP tween interval — content didn't
@@ -2518,6 +2532,18 @@ export async function computeStaticFrameSet(
25182532
hasTimelineCall: boolean;
25192533
};
25202534
const totalFrames = Math.max(1, Math.ceil(duration * fps));
2535+
if (!isStaticDedupFrameAnalysisSafe(totalFrames)) {
2536+
return {
2537+
totalFrames,
2538+
staticFrameSet: new Set<number>(),
2539+
hasVideo,
2540+
hasCanvas,
2541+
hasNonGsapAnim,
2542+
tweenCount,
2543+
eligible: false,
2544+
reason: `static-dedup frame analysis limit (${MAX_STATIC_DEDUP_ANALYSIS_FRAMES})`,
2545+
};
2546+
}
25212547
const animated = new Set<number>();
25222548
for (const { start, end } of intervals) {
25232549
const lo = Math.max(0, Math.floor(start * fps));

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -862,6 +862,7 @@ describe("GSAP rules", () => {
862862
expect(finding).toBeDefined();
863863
expect(finding?.severity).toBe("error");
864864
expect(finding?.message).toContain("repeat: -1");
865+
expect(finding?.fixHint).toContain("Math.max(0, Math.floor");
865866
});
866867

867868
it("does not error on finite repeat values", async () => {
@@ -881,6 +882,44 @@ describe("GSAP rules", () => {
881882
expect(finding).toBeUndefined();
882883
});
883884

885+
it("warns when a computed finite repeat can fall through to GSAP's -1 sentinel", async () => {
886+
const html = `
887+
<html><body>
888+
<div data-composition-id="main" data-width="1920" data-height="1080"></div>
889+
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
890+
<script>
891+
const duration = 0.5;
892+
const cycleDuration = 1;
893+
const tl = gsap.timeline({ paused: true, repeat: Math.floor(duration / cycleDuration) - 1 });
894+
window.__timelines = { main: tl };
895+
</script>
896+
</body></html>`;
897+
const result = await lintHyperframeHtml(html);
898+
const finding = result.findings.find((f) => f.code === "gsap_repeat_floor_unclamped");
899+
expect(finding?.severity).toBe("warning");
900+
expect(finding?.fixHint).toContain("Math.max(0, Math.floor");
901+
});
902+
903+
it("accepts a clamped computed finite repeat", async () => {
904+
const html = `
905+
<html><body>
906+
<div data-composition-id="main" data-width="1920" data-height="1080"></div>
907+
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
908+
<script>
909+
const duration = 0.5;
910+
const cycleDuration = 1;
911+
const tl = gsap.timeline({
912+
paused: true,
913+
repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1),
914+
});
915+
window.__timelines = { main: tl };
916+
</script>
917+
</body></html>`;
918+
const result = await lintHyperframeHtml(html);
919+
const finding = result.findings.find((f) => f.code === "gsap_repeat_floor_unclamped");
920+
expect(finding).toBeUndefined();
921+
});
922+
884923
it("does not error on repeat: -1 inside JavaScript comments", async () => {
885924
const html = `
886925
<html><body>

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

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1481,10 +1481,10 @@ export const gsapRules: LintRule<LintContext>[] = [
14811481
message:
14821482
"GSAP tween uses `repeat: -1` (infinite). Infinite repeats break the deterministic " +
14831483
"capture engine which seeks to exact frame times. Use a finite repeat count calculated " +
1484-
"from the composition duration: `repeat: Math.floor(duration / cycleDuration) - 1`.",
1484+
"from the composition duration: `repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)`.",
14851485
fixHint:
1486-
"Replace `repeat: -1` with a finite count, e.g. `repeat: Math.floor(totalDuration / singleCycleDuration) - 1`. " +
1487-
"Use Math.floor (not Math.ceil) to ensure the animation fits within the total duration.",
1486+
"Replace `repeat: -1` with a finite count, e.g. `repeat: Math.max(0, Math.floor(totalDuration / singleCycleDuration) - 1)`. " +
1487+
"Use Math.floor (not Math.ceil) so the animation fits, and clamp at zero so a short composition cannot evaluate to -1.",
14881488
snippet: truncateSnippet(snippet),
14891489
});
14901490
}
@@ -1510,14 +1510,41 @@ export const gsapRules: LintRule<LintContext>[] = [
15101510
"For example, Math.ceil(10.5 / 2) - 1 = 5 repeats → 6 cycles × 2s = 12s, exceeding 10.5s.",
15111511
fixHint:
15121512
"Use `Math.floor` instead of `Math.ceil` to ensure the animation fits within the duration: " +
1513-
"`repeat: Math.floor(totalDuration / cycleDuration) - 1`. " +
1513+
"`repeat: Math.max(0, Math.floor(totalDuration / cycleDuration) - 1)`. " +
15141514
"Math.floor(10.5 / 2) - 1 = 4 repeats → 5 cycles × 2s = 10s ✓",
15151515
snippet: truncateSnippet(snippet),
15161516
});
15171517
}
15181518
return findings;
15191519
},
15201520

1521+
// gsap_repeat_floor_unclamped
1522+
({ scripts }) => {
1523+
const findings: HyperframeLintFinding[] = [];
1524+
// A direct floor-minus-one expression becomes GSAP's infinite -1 sentinel when
1525+
// the visible duration is shorter than one full cycle. Math.max-wrapped forms
1526+
// intentionally do not match because `repeat:` is followed by Math.max, not Math.floor.
1527+
const pattern = /repeat\s*:\s*Math\.floor\s*\([^)]+\)\s*-\s*1/g;
1528+
for (const { snippet } of scanScriptsForRegexMatches(scripts, pattern, {
1529+
stripComments: false,
1530+
contextBefore: 40,
1531+
contextAfter: 40,
1532+
})) {
1533+
findings.push({
1534+
code: "gsap_repeat_floor_unclamped",
1535+
severity: "warning",
1536+
message:
1537+
"GSAP repeat calculation can evaluate to -1 when the composition is shorter than one cycle, " +
1538+
"which GSAP interprets as an infinite repeat.",
1539+
fixHint:
1540+
"Clamp the finite repeat count at zero: " +
1541+
"`repeat: Math.max(0, Math.floor(totalDuration / cycleDuration) - 1)`.",
1542+
snippet: truncateSnippet(snippet),
1543+
});
1544+
}
1545+
return findings;
1546+
},
1547+
15211548
// scene_layer_missing_visibility_kill
15221549
({ scripts, tags }) => {
15231550
const findings: HyperframeLintFinding[] = [];

‎packages/producer/src/services/render/planValidation.test.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,13 @@ import {
1111
BROWSER_GPU_NOT_SOFTWARE,
1212
DISTRIBUTED_DURATION_OUT_OF_RANGE,
1313
MAX_DISTRIBUTED_DURATION_SECONDS,
14+
MAX_RENDER_DURATION_SECONDS,
1415
PlanValidationError,
16+
RENDER_DURATION_OUT_OF_RANGE,
1517
SYSTEM_FONT_USED,
1618
parseFontFamilyValue,
1719
validateDistributedDuration,
20+
validateRenderDuration,
1821
validateNoGpuEncode,
1922
validateNoSystemFonts,
2023
} from "./planValidation.js";
@@ -95,6 +98,18 @@ describe("validateNoGpuEncode", () => {
9598
});
9699

97100
describe("validateDistributedDuration", () => {
101+
it("keeps the generic validator and legacy distributed API behavior aligned", () => {
102+
expect(MAX_RENDER_DURATION_SECONDS).toBe(MAX_DISTRIBUTED_DURATION_SECONDS);
103+
expect(RENDER_DURATION_OUT_OF_RANGE).toBe(DISTRIBUTED_DURATION_OUT_OF_RANGE);
104+
expect(() =>
105+
validateRenderDuration({
106+
duration: MAX_RENDER_DURATION_SECONDS,
107+
totalFrames: MAX_RENDER_DURATION_SECONDS * 30,
108+
fps: 30,
109+
}),
110+
).not.toThrow();
111+
});
112+
98113
it("accepts a finite duration within the distributed ceiling", () => {
99114
expect(() =>
100115
validateDistributedDuration({

‎packages/producer/src/services/render/planValidation.ts‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -67,17 +67,15 @@ export interface ValidateNoGpuEncodeInput {
6767
*/
6868
export const SYSTEM_FONT_USED = "SYSTEM_FONT_USED";
6969

70-
/**
71-
* Typed code for {@link validateDistributedDuration}. A duration this large
72-
* almost always means an unbounded runtime timeline escaped into plan(),
73-
* e.g. GSAP `repeat: -1` reporting its internal sentinel duration. Letting
74-
* that reach chunk planning creates billions of frames and turns an authoring
75-
* error into worker churn.
76-
*/
70+
/** Typed code for invalid duration metadata resolved by the shared browser probe. */
7771
export const DISTRIBUTED_DURATION_OUT_OF_RANGE = "DISTRIBUTED_DURATION_OUT_OF_RANGE";
72+
/** Generic alias; the legacy value remains stable for workflow retry policies. */
73+
export const RENDER_DURATION_OUT_OF_RANGE = DISTRIBUTED_DURATION_OUT_OF_RANGE;
7874

79-
/** Distributed renders are operationally bounded to one day of output. */
75+
/** All render paths are operationally bounded to one day of output. */
8076
export const MAX_DISTRIBUTED_DURATION_SECONDS = 24 * 60 * 60;
77+
/** Generic alias retained alongside the distributed public API. */
78+
export const MAX_RENDER_DURATION_SECONDS = MAX_DISTRIBUTED_DURATION_SECONDS;
8179

8280
/**
8381
* Reject any config that would let GPU encode or hardware-GL slip into a
@@ -143,13 +141,13 @@ export function validateNoSystemFonts(compiledHtml: string): void {
143141
}
144142
}
145143

146-
export function validateDistributedDuration(input: {
144+
export function validateRenderDuration(input: {
147145
duration: number;
148146
totalFrames: number;
149147
fps: number;
150148
}): void {
151149
const { duration, totalFrames, fps } = input;
152-
const maxFrames = Math.ceil(MAX_DISTRIBUTED_DURATION_SECONDS * fps);
150+
const maxFrames = Math.ceil(MAX_RENDER_DURATION_SECONDS * fps);
153151
if (
154152
Number.isFinite(duration) &&
155153
duration > 0 &&
@@ -163,12 +161,21 @@ export function validateDistributedDuration(input: {
163161
}
164162

165163
throw new PlanValidationError(
166-
DISTRIBUTED_DURATION_OUT_OF_RANGE,
167-
`[planValidation] Distributed render duration is out of range: ` +
164+
RENDER_DURATION_OUT_OF_RANGE,
165+
`[planValidation] Render duration is out of range: ` +
168166
`duration=${String(duration)}s totalFrames=${String(totalFrames)} fps=${String(fps)} ` +
169-
`(maxDuration=${String(MAX_DISTRIBUTED_DURATION_SECONDS)}s, maxFrames=${String(maxFrames)}). ` +
167+
`(maxDuration=${String(MAX_RENDER_DURATION_SECONDS)}s, maxFrames=${String(maxFrames)}). ` +
170168
`This usually means an unbounded timeline escaped into render planning, such as ` +
171169
`GSAP repeat:-1 / yoyo loops without an explicit finite root duration. Add a finite ` +
172170
`data-duration or replace infinite repeats with a finite repeat count before rendering.`,
173171
);
174172
}
173+
174+
/** Backward-compatible distributed entry point for existing adopters. */
175+
export function validateDistributedDuration(input: {
176+
duration: number;
177+
totalFrames: number;
178+
fps: number;
179+
}): void {
180+
validateRenderDuration(input);
181+
}

‎packages/producer/src/services/renderOrchestrator.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@ import {
147147
} from "./render/videoFrameCoverage.js";
148148
import { runCompileStage } from "./render/stages/compileStage.js";
149149
import { runProbeStage } from "./render/stages/probeStage.js";
150+
import { validateRenderDuration } from "./render/planValidation.js";
150151
import {
151152
runExtractVideosStage,
152153
shouldCopyExtractedFrames,
@@ -1971,6 +1972,11 @@ async function executeRenderPipeline(input: {
19711972
job.totalFrames = probeResult.totalFrames;
19721973
const totalFrames = probeResult.totalFrames;
19731974
captureTotalFrames = totalFrames;
1975+
validateRenderDuration({
1976+
duration: probeResult.duration,
1977+
totalFrames,
1978+
fps: fpsToNumber(job.config.fps),
1979+
});
19741980

19751981
perfStages.browserProbeMs = probeResult.browserProbeMs;
19761982
perfStages.compileMs = Date.now() - stage1Start;

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@
6666
"files": 26
6767
},
6868
"remotion-to-hyperframes": {
69-
"hash": "c96bb2f0af9e1143",
69+
"hash": "3a0e6c2affb9f74e",
7070
"files": 70
7171
},
7272
"slideshow": {

0 commit comments

Comments
 (0)