Skip to content

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

feat(types): phase 4 compile-time exhaustiveness with assertNever and targeted animation properties

okanaslb586707154b5
diff --git a/packages/compositions/src/compositions/canvas-composition.ts b/packages/compositions/src/compositions/canvas-composition.ts
index e715a1c8..54b41735 100644
--- a/packages/compositions/src/compositions/canvas-composition.ts
+++ b/packages/compositions/src/compositions/canvas-composition.ts
@@ -513,8 +513,8 @@ export async function drawCompositionTree(
opacity: Number(op.opacity ?? 1) * Number(props.opacity ?? 1),
isHeadless: props.isHeadless,
dpr:
- typeof (props as { dpr?: unknown }).dpr === "number"
- ? (props as { dpr: number }).dpr
+ typeof (props as unknown as { dpr?: unknown }).dpr === "number"
+ ? (props as unknown as { dpr: number }).dpr
: typeof (op as { dpr?: unknown }).dpr === "number"
? (op as { dpr: number }).dpr
: undefined,
diff --git a/packages/compositions/src/program/animation.ts b/packages/compositions/src/program/animation.ts
index d1e6f728..899ef191 100644
--- a/packages/compositions/src/program/animation.ts
+++ b/packages/compositions/src/program/animation.ts
@@ -274,17 +274,21 @@ function parseEase(ease?: string | EaseRef): EaseRef | undefined {
* Fluent builder and runtime representation for layer animations.
* Supports chainable keyframes, reactive signal binding, Perlin wiggles, and springs.
*/
-export class LayerAnimation implements LayerAnimationSpec {
- public tracks: AnimationTrack[] = [];
+export class LayerAnimation<TProp extends AnimatableProp = AnimatableProp>
+ implements LayerAnimationSpec<TProp>
+{
+ public tracks: AnimationTrack<TProp>[] = [];
/** Hold each value for this many frames (see {@link LayerAnimation.stepped}). */
public frameStep?: number;
- constructor(tracks: AnimationTrack[] = []) {
+ constructor(tracks: AnimationTrack<TProp>[] = []) {
this.tracks = [...tracks];
}
- public static create(): LayerAnimation {
- return new LayerAnimation();
+ public static create<
+ P extends AnimatableProp = AnimatableProp,
+ >(): LayerAnimation<P> {
+ return new LayerAnimation<P>();
}
/**
@@ -293,8 +297,10 @@ export class LayerAnimation implements LayerAnimationSpec {
* look of stop motion and cel animation. Applies to all of the layer's
* tracks, including ones added by other `.animate()` calls.
*/
- public static stepped(frames = 2): LayerAnimation {
- return new LayerAnimation().stepped(frames);
+ public static stepped<P extends AnimatableProp = AnimatableProp>(
+ frames = 2,
+ ): LayerAnimation<P> {
+ return new LayerAnimation<P>().stepped(frames);
}
/** See {@link LayerAnimation.stepped}. */
@@ -303,37 +309,37 @@ export class LayerAnimation implements LayerAnimationSpec {
return this;
}
- public static fromTo(
- prop: AnimatableProp,
+ public static fromTo<P extends AnimatableProp = AnimatableProp>(
+ prop: P,
fromValue: number | string | boolean,
toValue: number | string | boolean,
options: FromToOptions = {},
- ): LayerAnimation {
- return new LayerAnimation().fromTo(prop, fromValue, toValue, options);
+ ): LayerAnimation<P> {
+ return new LayerAnimation<P>().fromTo(prop, fromValue, toValue, options);
}
/** A track from a list of `[frame, value, ease?]` keyframes; see {@link LayerAnimation.keys}. */
- public static keys(
- prop: AnimatableProp,
+ public static keys<P extends AnimatableProp = AnimatableProp>(
+ prop: P,
keyframes: readonly KeyframeTuple[],
- ): LayerAnimation {
- return new LayerAnimation().keys(prop, keyframes);
+ ): LayerAnimation<P> {
+ return new LayerAnimation<P>().keys(prop, keyframes);
}
- public static signal(
- prop: AnimatableProp,
+ public static signal<P extends AnimatableProp = AnimatableProp>(
+ prop: P,
signalOrHandleId: unknown,
options: SignalTrackOptions = {},
- ): LayerAnimation {
- return new LayerAnimation().signal(prop, signalOrHandleId, options);
+ ): LayerAnimation<P> {
+ return new LayerAnimation<P>().signal(prop, signalOrHandleId, options);
}
- public static colorSignal(
- prop: AnimatableProp,
+ public static colorSignal<P extends AnimatableProp = AnimatableProp>(
+ prop: P,
signalOrHandleId: unknown,
options: ColorSignalOptions,
- ): LayerAnimation {
- return new LayerAnimation().colorSignal(prop, signalOrHandleId, options);
+ ): LayerAnimation<P> {
+ return new LayerAnimation<P>().colorSignal(prop, signalOrHandleId, options);
}
public static kineticSweep(
@@ -443,7 +449,7 @@ export class LayerAnimation implements LayerAnimationSpec {
return new LayerAnimation().fromTo("rotation", fromAngle, toAngle, options);
}
- public addTrack(track: AnimationTrack): this {
+ public addTrack(track: AnimationTrack<TProp>): this {
this.tracks.push(track);
return this;
}
@@ -471,12 +477,13 @@ export class LayerAnimation implements LayerAnimationSpec {
(t) => t.prop === prop && (!t.source || t.source.type === "keyframe"),
);
if (!track) {
- track = {
+ const newTrack: AnimationTrack<TProp> = {
id: `${prop}_fromTo_${this.tracks.length}`,
- prop,
+ prop: prop as TProp,
keyframes: [],
};
- this.tracks.push(track);
+ this.tracks.push(newTrack);
+ track = newTrack;
}
const id = track.id;
@@ -528,12 +535,13 @@ export class LayerAnimation implements LayerAnimationSpec {
(t) => t.prop === prop && (!t.source || t.source.type === "keyframe"),
);
if (!track) {
- track = {
+ const newTrack: AnimationTrack<TProp> = {
id: `${prop}_track_${this.tracks.length}`,
- prop,
+ prop: prop as TProp,
keyframes: [],
};
- this.tracks.push(track);
+ this.tracks.push(newTrack);
+ track = newTrack;
}
const parsedEase = parseEase(ease);
@@ -834,7 +842,7 @@ export class LayerAnimation implements LayerAnimationSpec {
this.tracks.push({
id,
- prop,
+ prop: prop as TProp,
source,
keyframes: [],
});
@@ -869,7 +877,7 @@ export class LayerAnimation implements LayerAnimationSpec {
this.tracks.push({
id,
- prop,
+ prop: prop as TProp,
source,
keyframes: [],
});
@@ -891,7 +899,7 @@ export class LayerAnimation implements LayerAnimationSpec {
this.tracks.push({
id,
- prop,
+ prop: prop as TProp,
source,
keyframes: [],
});
@@ -912,7 +920,7 @@ export class LayerAnimation implements LayerAnimationSpec {
this.tracks.push({
id,
- prop,
+ prop: prop as TProp,
source,
keyframes: [],
});
@@ -1033,7 +1041,7 @@ export class LayerAnimation implements LayerAnimationSpec {
* Attaches this animation to a target LayoutNode and returns the node.
*/
public applyTo<T extends { animation?: LayerAnimationSpec }>(node: T): T {
- node.animation = this.toSpec();
+ node.animation = this.toSpec() as unknown as LayerAnimationSpec;
return node;
}
@@ -1049,26 +1057,31 @@ export class LayerAnimation implements LayerAnimationSpec {
this.tracks = mergeAnimationTracks([
...this.tracks,
...others.flatMap((o) => o.tracks),
- ]);
+ ]) as unknown as AnimationTrack<TProp>[];
return this;
}
- public static merge(
- ...anims: Array<LayerAnimation | { tracks: AnimationTrack[] }>
- ): LayerAnimation {
- return new LayerAnimation().merge(...anims);
+ public static merge<P extends AnimatableProp = AnimatableProp>(
+ ...anims: Array<LayerAnimation<P> | { tracks: AnimationTrack<P>[] }>
+ ): LayerAnimation<P> {
+ const result = new LayerAnimation<P>();
+ result.tracks = mergeAnimationTracks(
+ anims.flatMap((o) => o.tracks),
+ ) as unknown as AnimationTrack<P>[];
+ return result;
}
/**
* Returns the validated LayerAnimation specification object.
*/
- public toSpec(): LayerAnimationSpec {
+ public toSpec(): LayerAnimationSpec<TProp> {
return {
tracks: this.tracks,
+ ...(this.frameStep !== undefined && { frameStep: this.frameStep }),
};
}
- public toJSON(): LayerAnimationSpec {
+ public toJSON(): LayerAnimationSpec<TProp> {
return this.toSpec();
}
}
diff --git a/packages/compositions/src/program/schema.ts b/packages/compositions/src/program/schema.ts
index 9c191ada..e9a83a2c 100644
--- a/packages/compositions/src/program/schema.ts
+++ b/packages/compositions/src/program/schema.ts
@@ -16,6 +16,7 @@
import {
Effect,
+ type EffectDomain,
type MeshAudioDeformConfig,
type TextSpan,
type TextSpanMark,
@@ -66,7 +67,7 @@ export interface EffectSpec<TOp extends string = string> {
}
export type ProgramEffect =
- | Effect<object>
+ | Effect<object, string, EffectDomain>
| EffectSpec
| (Record<string, unknown> & { op: string });
@@ -77,7 +78,7 @@ export const EffectSpecSchema = z.union([
op: z.string().min(1),
})
.passthrough(),
- z.custom<Effect<object>>((val) =>
+ z.custom<Effect<object, string, EffectDomain>>((val) =>
Boolean(
val &&
typeof val === "object" &&
@@ -193,6 +194,143 @@ export const AnimatablePropSchema = z.enum([
]);
export type AnimatableProp = z.infer<typeof AnimatablePropSchema>;
+export type SpatialAnimatableProp =
+ | "x"
+ | "y"
+ | "z"
+ | "scale"
+ | "scaleX"
+ | "scaleY"
+ | "scaleZ"
+ | "rotation"
+ | "rotateX"
+ | "rotateY"
+ | "rotateZ"
+ | "opacity"
+ | "width"
+ | "height"
+ | "hidden"
+ | "perspective"
+ | "perspectiveOriginX"
+ | "perspectiveOriginY"
+ | "translateZ"
+ | "motionBlurShutter";
+
+export type BoxAnimatableProp =
+ | SpatialAnimatableProp
+ | "gap"
+ | "padding"
+ | "borderRadius"
+ | "fill"
+ | "color"
+ | "borderColor"
+ | "borderWidth"
+ | "shininess"
+ | "roughness"
+ | "specularIntensity"
+ | "ambientIntensity"
+ | "metallic"
+ | "ior"
+ | "dispersion"
+ | "transmission"
+ | "fresnelPower"
+ | "emissive"
+ | "emissiveIntensity"
+ | "envIntensity"
+ | "exposure";
+
+export type TextAnimatableProp =
+ | SpatialAnimatableProp
+ | "text"
+ | "fontSize"
+ | "letterSpacing"
+ | "fill"
+ | "color"
+ | "rangeStart"
+ | "rangeEnd"
+ | "offset"
+ | "animatorRangeStart"
+ | "animatorRangeEnd"
+ | "animatorOffset"
+ | "firstMargin"
+ | "lastMargin"
+ | "baselineShift";
+
+export type ShapeAnimatableProp =
+ | SpatialAnimatableProp
+ | "d"
+ | "trimStart"
+ | "trimEnd"
+ | "trimOffset"
+ | "strokeWidth"
+ | "strokeDashOffset"
+ | "cornerRadius"
+ | "starInnerRadiusRatio"
+ | "fillColor"
+ | "strokeColor"
+ | "borderColor"
+ | "borderWidth";
+
+export type MediaAnimatableProp = SpatialAnimatableProp | "volume" | "muted";
+
+export type CameraAnimatableProp =
+ | SpatialAnimatableProp
+ | "cameraX"
+ | "cameraY"
+ | "cameraZ"
+ | "targetX"
+ | "targetY"
+ | "targetZ"
+ | "cameraPitch"
+ | "cameraYaw"
+ | "cameraRoll"
+ | "cameraFov"
+ | "cameraZoom"
+ | "focalLength"
+ | "focusDistance"
+ | "fStop"
+ | "maxBlurRadius"
+ | "shakeTranslation"
+ | "shakeRotation"
+ | "orbitRadius"
+ | "orbitAzimuth"
+ | "orbitElevation";
+
+export type LightAnimatableProp =
+ | SpatialAnimatableProp
+ | "intensity"
+ | "angle"
+ | "radius"
+ | "penumbra"
+ | "decay"
+ | "color";
+
+export type Model3DAnimatableProp =
+ | SpatialAnimatableProp
+ | "animationProgress"
+ | "animationTime"
+ | "animationSpeed"
+ | "wireframe";
+
+export type AnimatablePropsFor<TNode> = TNode extends { kind: "text" }
+ ? TextAnimatableProp
+ : TNode extends { kind: "shape" }
+ ? ShapeAnimatableProp
+ : TNode extends { kind: "media" }
+ ? MediaAnimatableProp
+ : TNode extends { kind: "camera" }
+ ? CameraAnimatableProp
+ : TNode extends { kind: "light" }
+ ? LightAnimatableProp
+ : TNode extends { kind: "model" } | { kind: "model3d" }
+ ? Model3DAnimatableProp
+ : TNode extends
+ | { kind: "flex" }
+ | { kind: "box" }
+ | { kind: "block" }
+ ? BoxAnimatableProp
+ : AnimatableProp;
+
export const MatteModeSchema = z.enum([
"alpha",
"alpha-inverted",
@@ -507,7 +645,11 @@ export const AnimationTrackSchema = z
durationFrames: z.number().int().min(1).optional(),
})
.strict();
-export type AnimationTrack = z.infer<typeof AnimationTrackSchema>;
+export type BaseAnimationTrack = z.infer<typeof AnimationTrackSchema>;
+export type AnimationTrack<TProp extends AnimatableProp = AnimatableProp> =
+ Omit<BaseAnimationTrack, "prop"> & {
+ prop: TProp;
+ };
export const LayerAnimationSchema = z
.object({
@@ -520,7 +662,12 @@ export const LayerAnimationSchema = z
})
.strict()
.superRefine(animationInvariants);
-export type LayerAnimationSpec = z.infer<typeof LayerAnimationSchema>;
+
+export type BaseLayerAnimationSpec = z.infer<typeof LayerAnimationSchema>;
+export type LayerAnimationSpec<TProp extends AnimatableProp = AnimatableProp> =
+ Omit<BaseLayerAnimationSpec, "tracks"> & {
+ tracks: AnimationTrack<TProp>[];
+ };
// ── layout node tree ──────────────────────────────────────────────────
// Hand-written interfaces anchor the mutual recursion (schema + type).
@@ -968,6 +1115,7 @@ export interface TextNode extends CompositionNodeBase {
export interface MediaNode extends CompositionNodeBase {
kind: "media";
inputHandleId: string;
+ src?: string;
dataType?: string;
fit?: "cover" | "contain" | "fill" | "none";
dpr?: number;
@@ -1485,6 +1633,7 @@ export const MediaNodeSchema: z.ZodType<MediaNode> = z
kind: z.literal("media"),
/** Graph binding — which connected input this node renders. */
inputHandleId: z.string().min(1),
+ src: z.string().optional(),
dataType: z.string().optional(),
fit: z.enum(["cover", "contain", "fill", "none"]).default("contain"),
dpr: z.number().min(1).max(4).optional(),
diff --git a/packages/compositions/src/program/stagger.ts b/packages/compositions/src/program/stagger.ts
index 3e0ed369..52f4fd1c 100644
--- a/packages/compositions/src/program/stagger.ts
+++ b/packages/compositions/src/program/stagger.ts
@@ -1,3 +1,5 @@
+import { assertNever } from "@framefields/core";
+
export type StaggerDirection = "forward" | "reverse" | "center-out";
/**
@@ -20,8 +22,9 @@ export function computeStaggerDelay(
return Math.round(dist * staggerFrames);
}
case "forward":
- default:
return index * staggerFrames;
+ default:
+ return assertNever(direction);
}
}
diff --git a/packages/compositions/src/program/to-virtual-media.ts b/packages/compositions/src/program/to-virtual-media.ts
index 6d60e170..e4bd1f28 100644
--- a/packages/compositions/src/program/to-virtual-media.ts
+++ b/packages/compositions/src/program/to-virtual-media.ts
@@ -58,7 +58,9 @@ function nodeToVirtualMedia(
const sourceRef =
node.kind === "media"
? (node.src ?? node.inputHandleId)
- : node.inputHandleId;
+ : "inputHandleId" in node
+ ? (node as { inputHandleId?: string }).inputHandleId
+ : undefined;
const isDirectMediaSource = (s: unknown) =>
typeof s === "string" &&
(s.startsWith("http://") ||
@@ -116,6 +118,7 @@ function nodeToVirtualMedia(
};
}
if (media && Array.isArray(node.effects)) {
+ let currentMedia: VirtualMediaData = media;
for (const eff of node.effects) {
const effOp =
eff &&
@@ -124,17 +127,19 @@ function nodeToVirtualMedia(
eff as { toOperation: () => Record<string, unknown> }
).toOperation()
: (eff as Record<string, unknown>);
- media = {
- metadata: { ...media.metadata },
+ currentMedia = {
+ metadata: { ...currentMedia.metadata },
operation: {
+ op: String(effOp.op ?? "effect"),
id: node.id ? `${node.id}-${effOp.op ?? "effect"}` : undefined,
effect: eff,
...effOp,
- dataType: media.operation.dataType,
+ dataType: currentMedia.operation.dataType,
},
- children: [media],
+ children: [currentMedia],
};
}
+ media = currentMedia;
}
if (media && node.vision) {
const visionRaw = node.vision as
diff --git a/packages/compositions/src/utils/layout/resolve-layout.ts b/packages/compositions/src/utils/layout/resolve-layout.ts
index 54158186..10410639 100644
--- a/packages/compositions/src/utils/layout/resolve-layout.ts
+++ b/packages/compositions/src/utils/layout/resolve-layout.ts
@@ -24,6 +24,7 @@
import type { Yoga, Node as YogaNode } from "yoga-layout/load";
export type { Yoga };
+import { assertNever } from "@framefields/core";
import { loadYoga } from "yoga-layout/load";
import type {
CompositionNodeBase,
@@ -173,8 +174,15 @@ function dirOf(node: LayoutNode): "row" | "column" | null {
return "column";
case "box":
return node.children && node.children.length > 0 ? "column" : null;
- default:
+ case "text":
+ case "media":
+ case "shape":
+ case "camera":
+ case "light":
+ case "model3d":
return null;
+ default:
+ return assertNever(node);
}
}
@@ -362,7 +370,7 @@ function buildYogaNode(
}
} else if (
node.kind === "text" ||
- (node.kind === "media" && (node as any).dataType === "Caption")
+ (node.kind === "media" && node.dataType === "Caption")
) {
// Leaf: text node uses dynamic setMeasureFunc for intrinsic sizing
yn.setMeasureFunc((width, widthMode, height, heightMode) => {
@@ -386,7 +394,7 @@ function buildYogaNode(
const measured = measure?.(node) ?? null;
if (measured) {
const hasRatio = node.aspectRatio !== undefined;
- const isCaption = (node as any).dataType === "Caption";
+ const isCaption = node.kind === "media" && node.dataType === "Caption";
const intrinsicRatio =
measured.height > 0 ? measured.width / measured.height : 1;
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index fca15a8d..b8faf372 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -5,6 +5,7 @@ export * from "./node-metadata.js";
export * from "./render-diagnostics.js";
export * from "./signals/index.js";
export * from "./types/index.js";
+export * from "./utils/assert.js";
export * from "./utils/color.js";
export * from "./utils/gradient.js";
export * from "./utils/is-equal.js";
diff --git a/packages/core/src/utils/assert.test.ts b/packages/core/src/utils/assert.test.ts
new file mode 100644
index 00000000..b7abb7e0
--- /dev/null
+++ b/packages/core/src/utils/assert.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import { assertNever } from "./assert.js";
+
+describe("assertNever", () => {
+ it("throws at runtime when called with unexpected value", () => {
+ expect(() => assertNever("unexpected" as never)).toThrow(
+ "Unhandled union variant: unexpected",
+ );
+
+ expect(() =>
+ assertNever({ op: "Unknown" } as never, "Custom message"),
+ ).toThrow("Custom message");
+ });
+
+ it("typechecks exhaustiveness in a discriminated union", () => {
+ type Shape = { kind: "circle"; r: number } | { kind: "square"; s: number };
+
+ function area(s: Shape): number {
+ switch (s.kind) {
+ case "circle":
+ return Math.PI * s.r * s.r;
+ case "square":
+ return s.s * s.s;
+ default:
+ return assertNever(s);
+ }
+ }
+
+ expect(area({ kind: "circle", r: 2 })).toBeCloseTo(12.566, 3);
+ expect(area({ kind: "square", s: 3 })).toBe(9);
+ expectTypeOf(assertNever).toBeFunction();
+ });
+});
diff --git a/packages/core/src/utils/assert.ts b/packages/core/src/utils/assert.ts
new file mode 100644
index 00000000..5e23416f
--- /dev/null
+++ b/packages/core/src/utils/assert.ts
@@ -0,0 +1,15 @@
+/**
+ * Compile-time exhaustiveness check helper for discriminated unions and enums.
+ *
+ * In switch statements or if-else ladders, passing the unhandled variable to
+ * `assertNever(x)` will fail TypeScript compilation if any variant was missed.
+ * At runtime, if an unexpected value arrives (e.g. from unvalidated JSON), it throws
+ * a descriptive Error.
+ */
+export function assertNever(value: never, message?: string): never {
+ const detail =
+ typeof value === "object" && value !== null
+ ? JSON.stringify(value)
+ : String(value);
+ throw new Error(message ?? `Unhandled union variant: ${detail}`);
+}
diff --git a/packages/framefields/src/effects/classes.ts b/packages/framefields/src/effects/classes.ts
index 09a090d6..ce977278 100644
--- a/packages/framefields/src/effects/classes.ts
+++ b/packages/framefields/src/effects/classes.ts
@@ -10,6 +10,13 @@ import type { EffectProp } from "./types.js";
// (./generated, written by scripts/generate-effects.mts). The classes below
// are still hand-written and move there in later phases of spec/sync-node.md.
export * from "./generated/index.js";
+
+import type {
+ AnyGeneratedAudioEffect,
+ AnyGeneratedVisualEffect,
+ GeneratedEffectConfigMap,
+} from "./generated/index.js";
+
export type { EffectProp } from "./types.js";
export interface LevelChannel {
diff --git a/packages/framefields/src/effects/generated/index.ts b/packages/framefields/src/effects/generated/index.ts
index d0156e34..a55bb45a 100644
--- a/packages/framefields/src/effects/generated/index.ts
+++ b/packages/framefields/src/effects/generated/index.ts
@@ -2,6 +2,100 @@
// Source of truth: nodes/*/package.json (`framefields`) and nodes/*/src/shared/config.ts.
// Regenerate with `pnpm run generate:effects`.
+import type { Blur, BlurProps } from "../custom/blur.js";
+import type {
+ Ascii,
+ AsciiProps,
+ AudioCompressor,
+ AudioCompressorProps,
+ AudioDelay,
+ AudioDelayProps,
+ AudioFade,
+ AudioFadeProps,
+ AudioNoiseGate,
+ AudioNoiseGateProps,
+ AudioParametricEq,
+ AudioParametricEqProps,
+ AudioReverb,
+ AudioReverbProps,
+ CameraParallax3D,
+ CameraParallax3DProps,
+ ChannelMerger,
+ ChannelMergerProps,
+ ChannelSplitter,
+ ChannelSplitterProps,
+ ColorBalance,
+ ColorBalanceProps,
+ ColorKey,
+ ColorKeyProps,
+ Contour,
+ ContourProps,
+ CornerPin,
+ CornerPinProps,
+ CRT,
+ CRTProps,
+ Datamosh,
+ DatamoshProps,
+ DisplacementMap,
+ DisplacementMapProps,
+ Dither,
+ DitherProps,
+ ExtractLUT,
+ ExtractLUTProps,
+ Flip,
+ FlipProps,
+ Gooey,
+ GooeyProps,
+ Iridescence,
+ IridescenceProps,
+ Kaleidoscope,
+ KaleidoscopeProps,
+ KenBurns,
+ KenBurnsProps,
+ LayerStyle,
+ LayerStyleProps,
+ Liquify,
+ LiquifyProps,
+ MaskMath,
+ MaskMathProps,
+ MeshWarp,
+ MeshWarpProps,
+ NoiseGenerator,
+ NoiseGeneratorProps,
+ OpArt,
+ OpArtProps,
+ Paint,
+ Painterly,
+ PainterlyProps,
+ PaintProps,
+ PatchHeal,
+ PatchHealProps,
+ Pixelate,
+ PixelateProps,
+ Posterize,
+ PosterizeProps,
+ ProceduralVFX,
+ ProceduralVFXProps,
+ RefineEdge,
+ RefineEdgeProps,
+ RefractionCaustics3D,
+ RefractionCaustics3DProps,
+ ResizerScaler,
+ ResizerScalerProps,
+ RGBSplit,
+ RGBSplitProps,
+ Rotate,
+ RotateProps,
+ StereoPanning,
+ StereoPanningProps,
+ Toon,
+ ToonProps,
+ Trails,
+ TrailsProps,
+ Vignette,
+ VignetteProps,
+} from "./classes.js";
+
export { Blur, type BlurProps } from "../custom/blur.js";
export {
Ascii,
diff --git a/packages/framefields/src/effects/golden.test.ts b/packages/framefields/src/effects/golden.test.ts
index c6774d84..5989db3f 100644
--- a/packages/framefields/src/effects/golden.test.ts
+++ b/packages/framefields/src/effects/golden.test.ts
@@ -40,10 +40,10 @@ function describeEffect(effect: Effect<object>) {
props: keys,
uniforms: round(uniforms),
payload: Object.fromEntries(
- keys.map((key) => [
- key,
- isSignal(payload[key]) ? "signal" : typeof payload[key],
- ]),
+ keys.map((key) => {
+ const val = (payload as Record<string, unknown>)[key];
+ return [key, isSignal(val) ? "signal" : typeof val];
+ }),
),
};
}
diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.ts
index e2eebe28..73f097c4 100644
--- a/packages/framefields/src/index.ts
+++ b/packages/framefields/src/index.ts
@@ -137,6 +137,8 @@ export {
import fs from "node:fs/promises";
import path from "node:path";
import {
+ type AnimatableProp,
+ type AnimatablePropsFor,
type AnimationTrack,
type BoxNode,
type CameraNode,
@@ -150,10 +152,15 @@ import {
type LightNode,
lintComposition,
type MatteMode,
+ type MediaAnimatableProp,
type MediaNode,
+ type Model3DAnimatableProp,
type Model3DNode,
mergeAnimationTracks,
+ type ShapeAnimatableProp,
type ShapeNode,
+ type SizeSpec,
+ type TextAnimatableProp,
type TextNode,
} from "@framefields/compositions/program";
import {
@@ -633,6 +640,14 @@ export {
} from "@framefields/compositions/program";
export * from "@framefields/core";
export * from "@framefields/renderers";
+export type {
+ AnimatablePropsFor,
+ TextAnimatableProp,
+ ShapeAnimatableProp,
+ MediaAnimatableProp,
+ Model3DAnimatableProp,
+ SizeSpec,
+};
export {
type AnimationClip3D,
type AudioLatentData,
@@ -2133,14 +2148,34 @@ export type AnimatableNode<
crop?: CropProps | Crop;
vision?: Vision;
relighting?: NormalRelightingOptions;
+ matte?: { node: LayoutNode; mode?: MatteMode };
deflicker?: DeflickerOptions;
- effects?: Effect<object>[];
+ effects?: CompatibleEffect<TCap>[];
blurRegions?: unknown[];
- animate(
+ animate<P extends AnimatableProp = AnimatableProp>(
...anim: (
- | LayerAnimation
- | { tracks: AnimationTrack[] }
- | LayerAnimation[]
+ | ([AnimatableProp] extends [P]
+ ? LayerAnimation
+ : LayerAnimation<P & AnimatablePropsFor<T>>)
+ | {
+ tracks: AnimationTrack<
+ [AnimatableProp] extends [P]
+ ? AnimatableProp
+ : P & AnimatablePropsFor<T>
+ >[];
+ }
+ | (
+ | ([AnimatableProp] extends [P]
+ ? LayerAnimation
+ : LayerAnimation<P & AnimatablePropsFor<T>>)
+ | {
+ tracks: AnimationTrack<
+ [AnimatableProp] extends [P]
+ ? AnimatableProp
+ : P & AnimatablePropsFor<T>
+ >[];
+ }
+ )[]
)[]
): AnimatableNode<T, TCap>;
pinToLandmark(
@@ -2392,7 +2427,7 @@ function withAnimation<
});
Object.defineProperty(target, "apply", {
- value: (effect: Effect<object>) => {
+ value: (effect: CompatibleEffect<TCap>) => {
if (!target.effects) {
target.effects = [];
}
@@ -2405,7 +2440,7 @@ function withAnimation<
});
Object.defineProperty(target, "withEffect", {
- value: (effect: Effect<object>) => {
+ value: (effect: CompatibleEffect<TCap>) => {
if (!target.effects) {
target.effects = [];
}
@@ -2418,7 +2453,7 @@ function withAnimation<
});
Object.defineProperty(target, "withEffects", {
- value: (effects: Effect<object>[]) => {
+ value: (effects: CompatibleEffect<TCap>[]) => {
if (!target.effects) {
target.effects = [];
}
@@ -2467,7 +2502,7 @@ function withAnimation<
if (!target.effects) {
target.effects = [];
}
- target.effects.push(blur);
+ target.effects.push(blur as CompatibleEffect<TCap>);
return target;
},
enumerable: false,
@@ -2826,7 +2861,9 @@ export const Layer = {
? -opts.x
: opts.x &&
typeof (opts.x as { multiply?: unknown }).multiply === "function"
- ? (opts.x as { multiply: (n: number) => unknown }).multiply(-1)
+ ? (
+ opts.x as unknown as { multiply: (n: number) => unknown }
+ ).multiply(-1)
: 0;
const innerY = target
@@ -2835,7 +2872,9 @@ export const Layer = {
? -opts.y
: opts.y &&
typeof (opts.y as { multiply?: unknown }).multiply === "function"
- ? (opts.y as { multiply: (n: number) => unknown }).multiply(-1)
+ ? (
+ opts.y as unknown as { multiply: (n: number) => unknown }
+ ).multiply(-1)
: 0;
const innerMedia = (
diff --git a/packages/framefields/src/type-safety.test.ts b/packages/framefields/src/type-safety.test.ts
index 02929606..1d6db114 100644
--- a/packages/framefields/src/type-safety.test.ts
+++ b/packages/framefields/src/type-safety.test.ts
@@ -5,11 +5,13 @@ import {
import { describe, expect, expectTypeOf, it } from "vitest";
import {
type AnimatableNode,
+ type AnimatablePropsFor,
type AnyAudioEffect,
type AnyEffect,
type AnyVisualEffect,
AudioCompressor,
AudioDelay,
+ assertNever,
Blur,
type CompatibleEffect,
FilmGrain,
@@ -24,7 +26,9 @@ import {
isFrameIndex,
isNormalized,
Layer,
+ LayerAnimation,
Levels,
+ type MediaAnimatableProp,
type MediaNode,
type Milliseconds,
ms,
@@ -36,7 +40,11 @@ import {
normalized,
type Seconds,
type SectionOptions,
+ type ShapeAnimatableProp,
+ type ShapeNode,
seconds,
+ type TextAnimatableProp,
+ type TextNode,
Vignette,
type VirtualMediaData,
} from "./index.js";
@@ -134,14 +142,18 @@ describe("Discriminated Effects & Port Capabilities (Phase 2)", () => {
});
it("narrows effect instances within AnyEffect discriminated union", () => {
- const effect: AnyEffect = new AudioDelay({ delayTime: 0.12 });
-
- if (effect.domain === "audio") {
- expectTypeOf(effect).toMatchTypeOf<AnyAudioEffect>();
- } else {
- expectTypeOf(effect).toMatchTypeOf<AnyVisualEffect>();
+ function inspectEffect(eff: AnyEffect) {
+ if (eff.domain === "audio") {
+ expectTypeOf(eff).toMatchTypeOf<AnyAudioEffect>();
+ } else {
+ expectTypeOf(eff).toMatchTypeOf<AnyVisualEffect>();
+ }
}
+ const effect: AnyEffect = new AudioDelay({ delayTime: 0.12 });
+ inspectEffect(effect);
+ inspectEffect(new Blur({ strength: 5 }));
+
if (effect.op === "AudioDelay") {
expect(effect.delayTime).toBe(0.12);
}
@@ -191,7 +203,7 @@ describe("Schema & Pipeline Unification (Phase 3)", () => {
expect(op.op).toBe("Blur");
expectTypeOf(op.op).toEqualTypeOf<"Blur">();
- expectTypeOf(op).toMatchTypeOf<NodeOperation<"Blur">>();
+ expectTypeOf(op).toMatchTypeOf<{ op: "Blur" }>();
});
it("validates effects via EffectSpecSchema and CompositorProgramSchema", () => {
@@ -251,3 +263,44 @@ describe("Schema & Pipeline Unification (Phase 3)", () => {
expectTypeOf<BlurMedia["operation"]["strength"]>().toEqualTypeOf<number>();
});
});
+
+describe("Targeted Animation Props & AST Exhaustiveness (Phase 4)", () => {
+ it("enforces assertNever on unhandled union variants", () => {
+ expect(() => assertNever("unexpected" as never)).toThrow(
+ "Unhandled union variant",
+ );
+ expect(() =>
+ assertNever("custom" as never, "Custom exhaustiveness error"),
+ ).toThrow("Custom exhaustiveness error");
+ });
+
+ it("narrows animatable properties by node kind", () => {
+ expectTypeOf<
+ AnimatablePropsFor<TextNode>
+ >().toMatchTypeOf<TextAnimatableProp>();
+ expectTypeOf<
+ AnimatablePropsFor<ShapeNode>
+ >().toMatchTypeOf<ShapeAnimatableProp>();
+ expectTypeOf<
+ AnimatablePropsFor<MediaNode>
+ >().toMatchTypeOf<MediaAnimatableProp>();
+
+ const shape = Layer.shape("circle");
+ const animTrim = LayerAnimation.fromTo("trimEnd", 0, 1);
+ expectTypeOf(animTrim).toEqualTypeOf<LayerAnimation<"trimEnd">>();
+ const animatedShape = shape.animate(animTrim);
+ expect(animatedShape.animation?.tracks.length).toBe(1);
+
+ const audio = Layer.audio("soundtrack.mp3");
+ const animVol = LayerAnimation.fromTo("volume", 0, 1);
+ expectTypeOf(animVol).toEqualTypeOf<LayerAnimation<"volume">>();
+ const animatedAudio = audio.animate(animVol);
+ expect(animatedAudio.animation?.tracks.length).toBe(1);
+
+ const text = Layer.text("hello");
+ const animFontSize = LayerAnimation.fromTo("fontSize", 24, 48);
+ expectTypeOf(animFontSize).toEqualTypeOf<LayerAnimation<"fontSize">>();
+ const animatedText = text.animate(animFontSize);
+ expect(animatedText.animation?.tracks.length).toBe(1);
+ });
+});
diff --git a/packages/tensor-webgpu/src/types.ts b/packages/tensor-webgpu/src/types.ts
index a3729b51..91f350a2 100644
--- a/packages/tensor-webgpu/src/types.ts
+++ b/packages/tensor-webgpu/src/types.ts
@@ -4,8 +4,8 @@ export type {
DeflickerOptions,
DepthNormalsOptions,
FaceLandmarksOptions,
- NormalRelightingOptions,
NormalizedLandmarkList,
+ NormalRelightingOptions,
OpticalFlowOptions,
PoseSkeletonOptions,
SegmentationOptions,
@@ -18,7 +18,7 @@ export type {
export type TensorSource =
| GPUTexture
- | { inputHandleId?: string; id?: string; [key: string]: unknown }
+ | { inputHandleId?: string; id?: string }
| string;
export interface TensorViewExport {
diff --git a/packages/vision/src/types.ts b/packages/vision/src/types.ts
index f708d7c8..fa6e4376 100644
--- a/packages/vision/src/types.ts
+++ b/packages/vision/src/types.ts
@@ -4,7 +4,7 @@ import type { DetectedObject, ObjectBoundingBox } from "@framefields/core";
export type VisionInputSource =
| string
- | { inputHandleId?: string; id?: string; [key: string]: unknown };
+ | { inputHandleId?: string; id?: string };
/** RGBA pixel buffer accepted by the runner. */
export interface VisionImageInput {
diff --git a/scripts/generate-effects.mts b/scripts/generate-effects.mts
index c0a12642..29e4d53e 100644
--- a/scripts/generate-effects.mts
+++ b/scripts/generate-effects.mts
@@ -601,6 +601,7 @@ function emitIndex(effects: EffectModel[], ctx: Context): string {
return [
BANNER,
+ ...importsFor(effects, "import"),
...importsFor(effects, "export"),
...(interfaces.length > 0
? [`export { ${interfaces.join(", ")} } from "./classes.js";`]