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.tsindex 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.tsindex 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.tsindex 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 = zdurationFrames: 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> = zkind: 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.tsindex 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.tsindex 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 asdiff --git a/packages/compositions/src/utils/layout/resolve-layout.ts b/packages/compositions/src/utils/layout/resolve-layout.tsindex 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 sizingyn.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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mtsindex 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";`]