Skip to content

Code-first video & image, rendered natively on WebGPU.

fix(compositions): replace the 128-keyframe cap with a lint warning

okanaslfaaffee46e4d
diff --git a/packages/components/SPEC.md b/packages/components/SPEC.md
index 414886ec..8b558e25 100644
--- a/packages/components/SPEC.md
+++ b/packages/components/SPEC.md
@@ -1112,8 +1112,8 @@ given, otherwise for 60 s, in whole loops.
- Mesh blobs are large radial-gradient boxes on Lissajous orbits (x at 1, y at 2 cycles
per loop, seeded phases); keys sit on each axis's extremes with `sine.inOut`, which is
an exact cosine (the pieces at the loop seam are `sine.out` / `sine.in`, close but not
- exact), so a loop costs 3–5 keys per axis and long scenes stay inside the 128-key
- limit. x and y live on separate nodes, each with its own limit.
+ exact), so a loop costs 3–5 keys per axis and long scenes stay small. x and y live on
+ separate nodes.
- The grid is one path and the dots one text node of `•` glyphs on the lattice (a path of
hundreds of circles renders in seconds; glyphs in milliseconds), each a cell larger than
the frame on every side, sliding one cell per loop and snapping back on the loop frame
@@ -1854,8 +1854,9 @@ Deviations from the specs as first written:
as the new word lands.
- Backdrop's loop seam is close to, not exactly, the cosine (the loop itself is exact).
- Keyframe `repeat` exists in the schema but nothing evaluates it, so loops are written out
- in whole periods up to the 128-key limit per track (about 24 loops on the busiest track;
- raise `loop` for very long scenes).
+ in whole periods, up to 960 keys per track (about 190 loops on the busiest track; raise
+ `loop` for longer scenes). This was 120 while the program schema capped a layer at 128
+ keyframes; that cap is gone (§20).
## 19. M8 delivery notes
@@ -1937,3 +1938,14 @@ Found by typechecking installed copies under user-style settings:
Budgets: MousePointer 62 → 66 KB and TextReveal 55 → 58 KB. Installed copies are bundled
from TypeScript source rather than the package's prebuilt output, which costs about 2 KB.
+
+**Keyframe cap removed.** The program schema rejected any layer with more than 128
+keyframes across its tracks. Nothing needed that: tracks are evaluated on the CPU from plain
+arrays, and playback compiles them to GSAP tweens. It rejected legitimate baked motion,
+though. The product demo's FocusZoom camera and pointer carry 318 and 205 keys, so its
+program failed validation. The cap is now a lint warning, `large_animation`, for layers over
+2000 keyframes, to catch keying every frame by mistake. Three components that worked around
+the cap lift it:
+- Backdrop's loop bound goes from 120 to 960 keys per track.
+- WordCycle no longer throws past 120 keys.
+- Selection no longer thins its keys.
diff --git a/packages/components/src/backdrop/index.test.ts b/packages/components/src/backdrop/index.test.ts
index bce55d68..10b2c817 100644
--- a/packages/components/src/backdrop/index.test.ts
+++ b/packages/components/src/backdrop/index.test.ts
@@ -64,11 +64,14 @@ describe("loop keys", () => {
expect(keys.length).toBeLessThanOrEqual(120);
});
- it("caps long spans under the key limit", () => {
- expect(cosineKeys(0, 10, 2, 0.3, 30, 30 * 1000).length).toBeLessThanOrEqual(
- 121,
- );
- expect(slideKeys(0, 10, 30, 30 * 1000).length).toBeLessThanOrEqual(121);
+ it("loops through long scenes, with a bound on very long ones", () => {
+ // 300 loops of 30 frames: the old 120-key cap stopped after ~24.
+ const long = cosineKeys(0, 10, 2, 0.3, 30, 30 * 150);
+ expect(long.at(-1)?.[0]).toBe(30 * 150);
+ expect(
+ cosineKeys(0, 10, 2, 0.3, 30, 30 * 10_000).length,
+ ).toBeLessThanOrEqual(961);
+ expect(slideKeys(0, 10, 30, 30 * 10_000).length).toBeLessThanOrEqual(961);
});
it("slides one cell a loop and snaps back on the loop frame", () => {
diff --git a/packages/components/src/backdrop/index.ts b/packages/components/src/backdrop/index.ts
index fd5c168f..29db26f9 100644
--- a/packages/components/src/backdrop/index.ts
+++ b/packages/components/src/backdrop/index.ts
@@ -28,8 +28,12 @@ export interface BackdropCues {
loops: ReadonlyArray<{ frame: number }>;
}
-/** Keys per track stay under the program's 128-per-animation limit. */
-const MAX_KEYS = 120;
+/**
+ * Keys per track, to bound program size on very long scenes (past it the
+ * last loop holds). A layer carries at most two looping tracks, so it stays
+ * under the `large_animation` lint threshold of 2000.
+ */
+const MAX_KEYS = 960;
export const backdrop = /* @__PURE__ */ defineComponent({
name: "Backdrop",
diff --git a/packages/components/src/selection/index.ts b/packages/components/src/selection/index.ts
index 5e39c988..a53f738e 100644
--- a/packages/components/src/selection/index.ts
+++ b/packages/components/src/selection/index.ts
@@ -189,7 +189,7 @@ export const selection = /* @__PURE__ */ defineComponent({
background: withAlpha(color, 0.32),
borderRadius: Math.max(1, 3 * s),
});
- const anim = LayerAnimation.create().keys("width", thin(keys));
+ const anim = LayerAnimation.create().keys("width", keys);
if (clear !== undefined)
anim.keys("opacity", [
[clear, 1],
@@ -321,16 +321,6 @@ export const selection = /* @__PURE__ */ defineComponent({
const round = (v: number) => Math.round(v * 100) / 100;
-/** Drop repeated hold keys past the program's per-track key budget, keeping the last. */
-function thin(keys: KeyframeTuple[]): KeyframeTuple[] {
- if (keys.length <= 120) return keys;
- const step = Math.ceil(keys.length / 119);
- return [
- ...keys.filter((_, i) => i % step === 0),
- keys[keys.length - 1] as KeyframeTuple,
- ];
-}
-
/** `#rrggbb` / `#rgb` at alpha `a`; other colours pass through. */
function withAlpha(color: string, a: number): string {
const hex = color.trim().replace(/^#/, "");
diff --git a/packages/components/src/word-cycle/index.ts b/packages/components/src/word-cycle/index.ts
index 77a8a456..07d739c2 100644
--- a/packages/components/src/word-cycle/index.ts
+++ b/packages/components/src/word-cycle/index.ts
@@ -24,9 +24,6 @@ export interface WordCycleCues {
changes: ReadonlyArray<{ frame: number; index: number; word: string }>;
}
-/** Keys per node stay under the program's 128-per-animation limit. */
-const MAX_KEYS = 120;
-
export const wordCycle = /* @__PURE__ */ defineComponent({
name: "WordCycle",
props: () => ({
@@ -151,10 +148,6 @@ export const wordCycle = /* @__PURE__ */ defineComponent({
prev = c.index;
}
}
- if (slotKeys.length > MAX_KEYS)
- throw new Error(
- `WordCycle: ${slotKeys.length} width keys exceed the ${MAX_KEYS}-key limit of one track. Use fewer \`cycles\` or shorter words.`,
- );
const add = (keys: KeyframeTuple[], by: number): KeyframeTuple[] =>
keys.map(([f, v, e]) =>
e ? [f, round((v as number) + by), e] : [f, round((v as number) + by)],
diff --git a/packages/compositions/src/program/lint.test.ts b/packages/compositions/src/program/lint.test.ts
index f7cb19c5..1730678a 100644
--- a/packages/compositions/src/program/lint.test.ts
+++ b/packages/compositions/src/program/lint.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { lintComposition } from "./lint.js";
+import { LARGE_ANIMATION_KEYFRAMES, lintComposition } from "./lint.js";
const base = { width: 1920, height: 1080, backgroundColor: "#000000" };
const codes = (layout: unknown[], extra = {}) =>
@@ -108,6 +108,30 @@ describe("lintComposition", () => {
).toEqual([]);
});
+ it("warns about very large animations, without a hard limit", () => {
+ const keyed = (n: number) => [
+ {
+ id: "busy",
+ kind: "box",
+ animation: {
+ tracks: [
+ {
+ prop: "x",
+ keyframes: Array.from({ length: n }, (_, f) => ({
+ frame: f,
+ value: f,
+ })),
+ },
+ ],
+ },
+ },
+ ];
+ expect(codes(keyed(LARGE_ANIMATION_KEYFRAMES))).toEqual([]);
+ expect(codes(keyed(LARGE_ANIMATION_KEYFRAMES + 1))).toEqual([
+ "large_animation",
+ ]);
+ });
+
it("flags tracks whose keyframes never change", () => {
expect(
codes([
diff --git a/packages/compositions/src/program/lint.ts b/packages/compositions/src/program/lint.ts
index 37716b3d..f091d5e0 100644
--- a/packages/compositions/src/program/lint.ts
+++ b/packages/compositions/src/program/lint.ts
@@ -25,6 +25,13 @@ const COLOR_PROPS = [
"color",
] as const;
+/**
+ * Keyframes on one layer past which an animation is probably keyed every
+ * frame by mistake. There is no hard limit: evaluation and playback handle
+ * any count, but programs this size are slow to send, read and edit.
+ */
+export const LARGE_ANIMATION_KEYFRAMES = 2000;
+
/** Contrast below this makes text hard to read (WCAG large-text minimum). */
const MIN_TEXT_CONTRAST = 3;
@@ -214,6 +221,19 @@ export function lintComposition(
}
}
+ const keyframeCount = tracksOf(node).reduce(
+ (n, t) => n + (t.keyframes?.length ?? 0),
+ 0,
+ );
+ if (keyframeCount > LARGE_ANIMATION_KEYFRAMES) {
+ push(
+ "warning",
+ "large_animation",
+ `'${id}' has ${keyframeCount} keyframes across its tracks (over ${LARGE_ANIMATION_KEYFRAMES}). Keying every frame is rarely needed: key the turning points and let eases fill in, or drive the prop from a signal.`,
+ id,
+ );
+ }
+
for (const t of tracksOf(node)) {
const kfs = t.keyframes ?? [];
if (
diff --git a/packages/compositions/src/program/schema.test.ts b/packages/compositions/src/program/schema.test.ts
index ca675645..32d7d27a 100644
--- a/packages/compositions/src/program/schema.test.ts
+++ b/packages/compositions/src/program/schema.test.ts
@@ -117,6 +117,30 @@ describe("CompositorProgramSchema (document v2)", () => {
);
});
+ it("has no keyframe cap: baked motion with hundreds of keys parses", () => {
+ const keyframes = Array.from({ length: 500 }, (_, f) => ({
+ id: `k${f}`,
+ frame: f,
+ value: f,
+ }));
+ const parsed = CompositorProgramSchema.safeParse({
+ ...heroConfig,
+ layout: [
+ {
+ id: "baked",
+ kind: "box",
+ animation: {
+ tracks: [
+ { id: "x", prop: "x", keyframes },
+ { id: "y", prop: "y", keyframes },
+ ],
+ },
+ },
+ ],
+ });
+ expect(parsed.success, JSON.stringify(parsed.error?.issues[0])).toBe(true);
+ });
+
it("recursive children parse at any depth (lazy recursion works)", () => {
const deepNode = (depth: number): LayoutNode => {
if (depth === 0) {
diff --git a/packages/compositions/src/program/schema.ts b/packages/compositions/src/program/schema.ts
index e61ae851..30f3350b 100644
--- a/packages/compositions/src/program/schema.ts
+++ b/packages/compositions/src/program/schema.ts
@@ -545,11 +545,9 @@ const animationInvariants = (
ctx: z.RefinementCtx,
) => {
if (!anim?.tracks) return;
- let totalKeyframes = 0;
for (let tIdx = 0; tIdx < anim.tracks.length; tIdx++) {
const track = anim.tracks[tIdx];
const keyframes = track.keyframes ?? [];
- totalKeyframes += keyframes.length;
const isKeyframeSource = !track.source || track.source.type === "keyframe";
if (isKeyframeSource && keyframes.length < 1) {
@@ -625,13 +623,6 @@ const animationInvariants = (
}
}
}
- if (totalKeyframes > 128) {
- ctx.addIssue({
- code: z.ZodIssueCode.custom,
- message: `Total keyframes across all tracks (${totalKeyframes}) exceeds the limit of 128.`,
- path: ["tracks"],
- });
- }
};
export const AnimationTrackSchema = z
diff --git a/packages/framefields/scripts/check-components-treeshake.mjs b/packages/framefields/scripts/check-components-treeshake.mjs
index 64592c3a..742ea7b4 100644
--- a/packages/framefields/scripts/check-components-treeshake.mjs
+++ b/packages/framefields/scripts/check-components-treeshake.mjs
@@ -51,7 +51,7 @@ const CONFETTI = "sparkles-";
const LOGO = "LogoReveal: give a `mark`";
const BACKDROP = "radial-gradient(rgba(0,0,0,0) 45%";
const WAVE = "Waveform: the audio was analysed";
-const WORDS = "width keys exceed the";
+const WORDS = 'exactly one "{}" slot';
const DEVICE = "status-battery";
const TOUCH = "-ripple-";
const SPLIT = "before-clip";