@framefields/node-compositor 0.0.0-stage → 2.0.2

package/src/shared/config.ts

@@ -0,0 +1,44 @@
+import {
+	type CompositorProgramConfig,
+	CompositorProgramSchema,
+} from "@framefields/compositions/program";
+import { MediaMetadataSchema } from "@framefields/core";
+import { ImageResultSchema, VideoResultSchema } from "@framefields/node-sdk";
+import { z } from "zod";
+
+/**
+ * v2 config — THE document (spec: SKILL.md).
+ * No `layers`, no `layerUpdates`, no aliases. The node config IS the
+ * composition program: strict zod, validated by the E-code pre-parse scan
+ * in `@framefields/compositions/program/validate`.
+ */
+export const CompositorNodeConfigSchema = CompositorProgramSchema;
+export type CompositorNodeConfig = CompositorProgramConfig;
+
+/** Data types accepted by the variable composer inputs. */
+export const VariableInputDataTypes = [
+	"Text",
+	"Image",
+	"Video",
+	"Audio",
+	"Caption",
+	"SVG",
+	"GIF",
+	"Lottie",
+	"Signal",
+] as const;
+export type VariableInputDataType = (typeof VariableInputDataTypes)[number];
+
+/** The Compositor op framing (used in the render tree, per processCompositor). */
+export const CompositorOperationSchema = CompositorNodeConfigSchema.extend({
+	op: z.literal("Compositor"),
+	dataType: z.enum(["Video", "Image"]).optional(),
+	metadata: MediaMetadataSchema.optional(),
+}).strict();
+
+export type CompositorOperation = z.infer<typeof CompositorOperationSchema>;
+
+export const CompositorResultSchema = z.union([
+	VideoResultSchema,
+	ImageResultSchema,
+]);

package/src/shared/index.ts

@@ -0,0 +1,3 @@
+export * from "./compiler.js";
+export * from "./config.js";
+export * from "./presets.js";

package/src/shared/kinetic-typography.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from "vitest";
+import { compileTimeline } from "./compiler.js";
+
+describe("Kinetic Typography Engine Integration (Section 5)", () => {
+	it("compiles keyframe tracks for offset, rangeStart, and rangeEnd", () => {
+		const virtualMedia = {
+			operation: {
+				op: "Compositor",
+				width: 1920,
+				height: 1080,
+			},
+			children: [
+				{
+					operation: {
+						op: "CompositorLayer",
+						id: "text-kinetic-1",
+						kind: "text",
+						text: "KINETIC MOTION GRAPHICS",
+						fontSize: 64,
+						startFrame: 0,
+						durationFrames: 60,
+						animators: [
+							{
+								id: "wave-rise",
+								unit: "character" as const,
+								rangeStart: 0,
+								rangeEnd: 1,
+								offset: -1,
+								easing: "power2.out",
+								transform: {
+									y: 40,
+									scale: 0.8,
+									rotation: 10,
+									rotationX: 90,
+									opacity: 0,
+									blur: 12,
+								},
+							},
+						],
+						animation: {
+							tracks: [
+								{
+									id: "track-offset",
+									prop: "offset" as const,
+									keyframes: [
+										{ id: "kf-0", frame: 0, value: -1 },
+										{
+											id: "kf-1",
+											frame: 48,
+											value: 1,
+											ease: { name: "power2" as const, dir: "out" as const },
+										},
+									],
+								},
+							],
+						},
+					},
+				},
+			],
+		};
+
+		const { tl, targetsById } = compileTimeline("test-kinetic", virtualMedia, {
+			fps: 24,
+			durationSec: 3,
+		});
+
+		const stub = targetsById["text-kinetic-1"];
+		expect(stub).toBeDefined();
+
+		// Seek to frame 0
+		tl.seek(0);
+		expect(stub.offset).toBeCloseTo(-1);
+
+		// Seek to frame 48 (2.0s at 24fps)
+		tl.seek(2.0);
+		expect(stub.offset).toBeCloseTo(1);
+
+		// Seek to midpoint frame 24 (1.0s at 24fps)
+		tl.seek(1.0);
+		expect(stub.offset).toBeGreaterThan(-1);
+		expect(stub.offset).toBeLessThan(1);
+	});
+
+	it("supports word and line units on kinetic text animators", () => {
+		const virtualMedia = {
+			operation: {
+				op: "Compositor",
+				width: 1920,
+				height: 1080,
+			},
+			children: [
+				{
+					operation: {
+						op: "CompositorLayer",
+						id: "text-words",
+						kind: "text",
+						text: "HELLO WORLD FROM GATEWAI",
+						fontSize: 48,
+						startFrame: 0,
+						durationFrames: 30,
+						animators: [
+							{
+								id: "word-pop",
+								unit: "word" as const,
+								rangeStart: 0.2,
+								rangeEnd: 0.8,
+								offset: 0,
+								transform: {
+									scale: 1.3,
+									y: -15,
+								},
+							},
+							{
+								id: "line-slide",
+								unit: "line" as const,
+								rangeStart: 0,
+								rangeEnd: 1,
+								offset: 0,
+								transform: {
+									x: 20,
+								},
+							},
+						],
+					},
+				},
+			],
+		};
+
+		const { targetsById } = compileTimeline("test-words", virtualMedia, {
+			fps: 24,
+			durationSec: 2,
+		});
+
+		const stub = targetsById["text-words"];
+		expect(stub).toBeDefined();
+		expect(stub.scale).toBe(1);
+	});
+});

package/src/shared/presets.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from "vitest";
+import {
+	chipsForLayer,
+	getPresetDetails,
+	materializePreset,
+} from "./presets.js";
+
+describe("Compositor Presets", () => {
+	it("should return correct details for standard preset types", () => {
+		expect(getPresetDetails("fade-in")).toEqual({
+			kind: "entrance",
+			label: "Fade In",
+		});
+		expect(getPresetDetails("fade-out")).toEqual({
+			kind: "exit",
+			label: "Fade Out",
+		});
+		expect(getPresetDetails("pulse")).toEqual({
+			kind: "emphasis",
+			label: "Pulse",
+		});
+	});
+
+	it("should materialize fade-in preset correctly", () => {
+		const base = {
+			x: 100,
+			y: 200,
+			scale: 1.5,
+			rotation: 45,
+			opacity: 0.8,
+			durationFrames: 100,
+		};
+
+		const tracks = materializePreset(base, "fade-in", {
+			width: 1920,
+			height: 1080,
+			fps: 24,
+			presetGroupId: "fade-in-group",
+		});
+		expect(tracks).toHaveLength(1);
+		expect(tracks[0].prop).toBe("opacity");
+		expect(tracks[0].keyframes).toHaveLength(2);
+		expect(tracks[0].keyframes[0].frame).toBe(0);
+		expect(tracks[0].keyframes[0].value).toBe(0);
+		expect(tracks[0].keyframes[0].presetGroupId).toBe("fade-in-group");
+		expect(tracks[0].keyframes[1].frame).toBe(24); // default duration matches fps (24)
+		expect(tracks[0].keyframes[1].value).toBe(0.8); // layerBase.opacity
+		expect(tracks[0].keyframes[1].ease).toEqual({ name: "none", dir: "out" });
+	});
+
+	it("should materialize slide-in-left preset correctly", () => {
+		const base = {
+			x: 100,
+			y: 200,
+			scale: 1.5,
+			rotation: 45,
+			opacity: 0.8,
+			durationFrames: 100,
+		};
+
+		const tracks = materializePreset(base, "slide-in-left", {
+			width: 1920,
+			height: 1080,
+			fps: 24,
+			presetGroupId: "slide-left-group",
+		});
+		expect(tracks).toHaveLength(1);
+		expect(tracks[0].prop).toBe("x");
+		expect(tracks[0].keyframes).toHaveLength(2);
+		expect(tracks[0].keyframes[0].value).toBe(100 - 1920); // x - width
+		expect(tracks[0].keyframes[1].value).toBe(100); // base.x
+	});
+
+	it("should derive chips from layer keyframes correctly", () => {
+		const layer = {
+			animation: {
+				tracks: [
+					{
+						id: "track-1",
+						prop: "opacity" as const,
+						keyframes: [
+							{ id: "kf-1", frame: 0, value: 0, presetGroupId: "fade-in_123" },
+							{
+								id: "kf-2",
+								frame: 24,
+								value: 1,
+								ease: { name: "none" as const, dir: "out" as const },
+								presetGroupId: "fade-in_123",
+							},
+						],
+					},
+					{
+						id: "track-2",
+						prop: "scale" as const,
+						keyframes: [
+							{ id: "kf-3", frame: 48, value: 1, presetGroupId: "pulse_456" },
+							{
+								id: "kf-4",
+								frame: 60,
+								value: 1.2,
+								ease: { name: "sine" as const, dir: "inOut" as const },
+								presetGroupId: "pulse_456",
+							},
+						],
+					},
+				],
+			},
+		};
+
+		const chips = chipsForLayer(layer);
+		expect(chips).toHaveLength(2);
+
+		const fadeInChip = chips.find((c) => c.presetType === "fade-in");
+		expect(fadeInChip).toBeDefined();
+		expect(fadeInChip?.kind).toBe("entrance");
+		expect(fadeInChip?.durationFrames).toBe(24);
+		expect(fadeInChip?.ease).toEqual({ name: "none", dir: "out" });
+
+		const pulseChip = chips.find((c) => c.presetType === "pulse");
+		expect(pulseChip).toBeDefined();
+		expect(pulseChip?.kind).toBe("emphasis");
+		expect(pulseChip?.durationFrames).toBe(12);
+	});
+
+	it("should materialize text animation presets (typewriter, word-reveal, line-reveal, karaoke)", () => {
+		const base = {
+			x: 0,
+			y: 0,
+			scale: 1,
+			rotation: 0,
+			opacity: 1,
+			durationFrames: 60,
+		};
+
+		for (const preset of [
+			"typewriter",
+			"word-reveal",
+			"line-reveal",
+			"karaoke",
+		]) {
+			const tracks = materializePreset(base, preset, {
+				width: 1920,
+				height: 1080,
+				fps: 30,
+				presetGroupId: `${preset}_grp`,
+			});
+			expect(tracks).toHaveLength(1);
+			expect(tracks[0].prop).toBe("text");
+			expect(tracks[0].keyframes).toHaveLength(2);
+			expect(tracks[0].keyframes[0].value).toBe(0);
+			expect(tracks[0].keyframes[0].frame).toBe(0);
+			expect(tracks[0].keyframes[1].value).toBe(1);
+			expect(tracks[0].keyframes[1].frame).toBe(30);
+			expect(tracks[0].keyframes[1].presetType).toBe(preset);
+
+			const details = getPresetDetails(preset);
+			expect(details.kind).toBe("entrance");
+		}
+	});
+
+	it("should materialize modern motion presets (tracking-expand, blur-reveal, kinetic-wave, slice-wipe)", () => {
+		const base = {
+			x: 100,
+			y: 200,
+			scale: 1,
+			rotation: 0,
+			opacity: 1,
+			width: 400,
+			height: 300,
+			durationFrames: 60,
+		};
+
+		// Tracking expand
+		const teTracks = materializePreset(base, "tracking-expand", {
+			width: 1920,
+			height: 1080,
+			fps: 30,
+		});
+		expect(teTracks).toHaveLength(1);
+		expect(teTracks[0].prop).toBe("letterSpacing");
+		expect(teTracks[0].keyframes[1].value).toBe(24);
+
+		// Blur reveal
+		const brTracks = materializePreset(base, "blur-reveal", {
+			width: 1920,
+			height: 1080,
+			fps: 30,
+		});
+		expect(brTracks).toHaveLength(1);
+		expect(brTracks[0].prop).toBe("opacity");
+		expect(brTracks[0].keyframes[0].value).toBe(0);
+		expect(brTracks[0].keyframes[1].value).toBe(1);
+
+		// Kinetic wave
+		const kwTracks = materializePreset(base, "kinetic-wave", {
+			width: 1920,
+			height: 1080,
+			fps: 30,
+		});
+		expect(kwTracks).toHaveLength(1);
+		expect(kwTracks[0].prop).toBe("y");
+		expect(kwTracks[0].repeat).toBe(3);
+		expect(kwTracks[0].yoyo).toBe(true);
+
+		// Slice wipe
+		const swTracks = materializePreset(base, "slice-wipe", {
+			width: 1920,
+			height: 1080,
+			fps: 30,
+		});
+		expect(swTracks).toHaveLength(1);
+		expect(swTracks[0].prop).toBe("x");
+		expect(swTracks[0].keyframes[0].value).toBe(100 - 400);
+		expect(swTracks[0].keyframes[1].value).toBe(100);
+	});
+});
+