Skip to content

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

70.8 KB
Raw Blame
/**
 * Compositor program document v2 — THE single source of truth for a
 * composition (spec: `nodes/node-compositor/SKILL.md`).
 *
 * The config IS a tree of HTML-like layout nodes (`layout`), replacing the
 * v1 flat `layers[]`. No `layers`, no `layerUpdates`, no aliases: the tree
 * is what agents write, what the editor edits, what the renderer renders.
 *
 * Design rules (hard):
 *  - strict zod, `.strict()` everywhere; unknown keys are rejected by the
 *    pre-parse scan in `validate.ts` (zod alone would silently strip them)
 *  - recursive container fields use `z.lazy`; leaf kinds are plain objects
 *  - every field that can animate is in `AnimatablePropSchema`
 *  - no backwards compatibility: v1 shapes fail fast with E-codes
 */

import {
	Effect,
	type EffectDomain,
	type GeometryOutlineOptions,
	type MediaTimeRemapInput,
	MediaTimeRemapInputSchema,
	type MeshAudioDeformConfig,
	type TextSpan,
	type TextSpanMark,
	type ToonShading,
	validateMediaTimeRemap,
} from "@framefields/core";
import { ColorSchema } from "@framefields/node-sdk";
import {
	type AimConstraint,
	AimSchema,
	type CrowdConfig,
	CrowdSchema,
	type JointDriver,
	JointDriverSchema,
	type JointPose,
	JointPoseSchema,
	type LookAtConstraint,
	LookAtSchema,
	type ModelAnimationLayer,
	ModelAnimationLayerSchema,
	type NumberTrack,
	NumberTrackSchema,
	type SpringBoneChain,
	SpringBoneChainSchema,
	type TwoBoneIkConstraint,
	TwoBoneIkSchema,
} from "./character-schema.js";
import {
	Fracture3DSchema,
	type Fracture3DSpec,
	Primitive3DSpecSchema,
	Scatter3DSchema,
	type Scatter3DSpec,
	TextureLayerSchema,
	type WindConfig,
	WindSchema,
} from "./procedural-schema.js";
export type { TextSpan, TextSpanMark };
export type { ToonShading, GeometryOutlineOptions };

import {
	type AdvancedTextAnimator,
	AdvancedTextAnimatorSchema,
	type AETextAnimator,
	AETextAnimatorSchema,
	type KineticMarqueeConfig,
	KineticMarqueeConfigSchema,
	type TextPathOptions,
	TextPathOptionsSchema,
	type TypewriterAnimator,
	TypewriterAnimatorSchema,
} from "@framefields/webgpu-renderers/text-animations";
import { z } from "zod";

export * from "@framefields/webgpu-renderers/text-animations";

// ── shared leaf primitives ────────────────────────────────────────────

/** number px | "auto" (intrinsic) | "fit" (shrink-wrap) | "fill" (parent extent). */
export const SizeSpecSchema = z.union([
	z.number().min(0),
	z.enum(["auto", "fit", "fill"]),
	z.custom<unknown>(),
]);
export type SizeSpec = z.infer<typeof SizeSpecSchema>;

export const ShapeTypeSchema = z.enum([
	"rect",
	"circle",
	"ellipse",
	"polygon",
	"star",
	"arrow",
	"path",
]);
export type ShapeType = z.infer<typeof ShapeTypeSchema>;

export interface EffectSpec<TOp extends string = string> {
	op: TOp;
	[key: string]: unknown;
}

export type ProgramEffect =
	| Effect<object, string, EffectDomain>
	| EffectSpec
	| (Record<string, unknown> & { op: string });

export const EffectSpecSchema = z.union([
	z.instanceof(Effect),
	z
		.object({
			op: z.string().min(1),
		})
		.passthrough(),
	z.custom<Effect<object, string, EffectDomain>>((val) =>
		Boolean(
			val &&
				typeof val === "object" &&
				"op" in val &&
				typeof (val as { op: unknown }).op === "string",
		),
	),
]);

export const AnimatablePropSchema = z.enum([
	"x",
	"y",
	"scale",
	"rotation",
	"opacity",
	"width",
	"height",
	"volume",
	"hidden",
	"muted",
	"gap",
	"padding",
	"borderRadius",
	"fontSize",
	"text",
	"fill",
	"color",
	"letterSpacing",
	// Vector Shape & Stroke properties
	/** A shape's SVG path: keyframed paths morph into each other. */
	"d",
	"trimStart",
	"trimEnd",
	"trimOffset",
	"strokeWidth",
	"strokeDashOffset",
	"cornerRadius",
	"starInnerRadiusRatio",
	"fillColor",
	"strokeColor",
	"borderColor",
	"borderWidth",
	"motionBlurShutter",
	// Kinetic Typography properties
	"rangeStart",
	"rangeEnd",
	"offset",
	"animatorRangeStart",
	"animatorRangeEnd",
	"animatorOffset",
	// Path-following text properties
	"firstMargin",
	"lastMargin",
	"baselineShift",
	// 3D Perspective & Transform properties
	"rotateX",
	"rotateY",
	"rotateZ",
	"perspective",
	"translateZ",
	"perspectiveOriginX",
	"perspectiveOriginY",
	// 3D Camera & Scene properties
	"cameraX",
	"cameraY",
	"cameraZ",
	"targetX",
	"targetY",
	"targetZ",
	"cameraPitch",
	"cameraYaw",
	"cameraRoll",
	"cameraFov",
	"cameraZoom",
	"focalLength",
	"focusDistance",
	"fStop",
	"maxBlurRadius",
	"shakeTranslation",
	"shakeRotation",
	"relativitySpeed",
	"orbitRadius",
	"orbitAzimuth",
	"orbitElevation",
	"z",
	"scaleZ",
	// 3D Lighting & Material properties
	"intensity",
	"angle",
	"radius",
	"penumbra",
	"decay",
	"shininess",
	"roughness",
	"specularIntensity",
	"ambientIntensity",
	"metallic",
	"ior",
	"dispersion",
	"transmission",
	"fresnelPower",
	"envIntensity",
	// 3D Model & Animation properties
	"animationProgress",
	"animationTime",
	"animationSpeed",
	"wireframe",
	"scaleX",
	"scaleY",
	// Physically based surfaces & world
	"emissive",
	"emissiveIntensity",
	"clearcoat",
	"clearcoatRoughness",
	"anisotropy",
	"anisotropyRotation",
	"subsurface",
	"subsurfaceColor",
	"sheen",
	"sheenColor",
	"sheenRoughness",
	"iridescence",
	"iridescenceThickness",
	"iridescenceIor",
	"triplanarScale",
	"triplanarSharpness",
	"exposure",
	"volumetricFogDensity",
	"volumetricFogAnisotropy",
	"volumetricFogNoiseStrength",
]);
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 MaterialAnimatableProp =
	| "shininess"
	| "roughness"
	| "specularIntensity"
	| "ambientIntensity"
	| "metallic"
	| "ior"
	| "dispersion"
	| "transmission"
	| "fresnelPower"
	| "emissive"
	| "emissiveIntensity"
	| "clearcoat"
	| "clearcoatRoughness"
	| "anisotropy"
	| "anisotropyRotation"
	| "subsurface"
	| "subsurfaceColor"
	| "sheen"
	| "sheenColor"
	| "sheenRoughness"
	| "iridescence"
	| "iridescenceThickness"
	| "iridescenceIor"
	| "triplanarScale"
	| "triplanarSharpness"
	| "envIntensity"
	| "exposure";

export type BoxAnimatableProp =
	| SpatialAnimatableProp
	| MaterialAnimatableProp
	| "gap"
	| "padding"
	| "borderRadius"
	| "fill"
	| "color"
	| "borderColor"
	| "borderWidth";

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"
	| "relativitySpeed"
	| "orbitRadius"
	| "orbitAzimuth"
	| "orbitElevation";

export type LightAnimatableProp =
	| SpatialAnimatableProp
	| "targetX"
	| "targetY"
	| "targetZ"
	| "intensity"
	| "angle"
	| "radius"
	| "penumbra"
	| "decay"
	| "color"
	| "exposure"
	| "volumetricFogDensity"
	| "volumetricFogAnisotropy"
	| "volumetricFogNoiseStrength";

export type Model3DAnimatableProp =
	| SpatialAnimatableProp
	| MaterialAnimatableProp
	| "color"
	| "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",
	"luma",
	"luma-inverted",
]);
export type MatteMode = z.infer<typeof MatteModeSchema>;

export const MaterialTypeSchema = z.enum([
	"lit",
	"unlit",
	"toon",
	"glass",
	"acrylic",
	"frosted",
	"metallic",
]);
export type MaterialType = z.infer<typeof MaterialTypeSchema>;

export const EXTENDED_3D_ANIMATABLE_PROPS = [
	"rotateX",
	"rotateY",
	"rotateZ",
	"perspective",
	"translateZ",
	"perspectiveOriginX",
	"perspectiveOriginY",
	"cameraX",
	"cameraY",
	"cameraZ",
	"targetX",
	"targetY",
	"targetZ",
	"cameraPitch",
	"cameraYaw",
	"cameraRoll",
	"cameraFov",
	"cameraZoom",
	"focalLength",
	"focusDistance",
	"fStop",
	"maxBlurRadius",
	"shakeTranslation",
	"shakeRotation",
	"relativitySpeed",
	"orbitRadius",
	"orbitAzimuth",
	"orbitElevation",
	"z",
	"scaleZ",
	"intensity",
	"angle",
	"radius",
	"penumbra",
	"decay",
	"shininess",
	"roughness",
	"specularIntensity",
	"ambientIntensity",
	"metallic",
] as const;
export type Extended3DAnimatableProp =
	(typeof EXTENDED_3D_ANIMATABLE_PROPS)[number];

export const SignalColorModeSchema = z.enum([
	"interpolate",
	"hueRotate",
	"threshold",
]);
export type SignalColorMode = z.infer<typeof SignalColorModeSchema>;

export const EaseRefSchema = z
	.object({
		name: z.enum([
			"none",
			"power1",
			"power2",
			"power3",
			"sine",
			"circ",
			"expo",
			"back",
			"elastic",
			"bounce",
			"spring",
			"cubic",
			"hold",
		]),
		dir: z.enum(["in", "out", "inOut"]),
		params: z.array(z.number()).optional(),
	})
	.strict()
	.superRefine((data, ctx) => {
		if (data.name === "spring" && data.params) {
			const [damping, stiffness, mass] = data.params;
			if (damping !== undefined && damping <= 0) {
				ctx.addIssue({
					code: z.ZodIssueCode.custom,
					message: "Spring damping must be greater than 0.",
					path: ["params", 0],
				});
			}
			if (stiffness !== undefined && stiffness <= 0) {
				ctx.addIssue({
					code: z.ZodIssueCode.custom,
					message: "Spring stiffness must be greater than 0.",
					path: ["params", 1],
				});
			}
			if (mass !== undefined && mass <= 0) {
				ctx.addIssue({
					code: z.ZodIssueCode.custom,
					message: "Spring mass must be greater than 0.",
					path: ["params", 2],
				});
			}
		}
	});
export type EaseRef = z.infer<typeof EaseRefSchema>;

export const KeyframeSchema = z
	.object({
		id: z.string().min(1),
		frame: z.number().int().min(0),
		value: z.union([z.number(), z.boolean(), z.string()]),
		ease: EaseRefSchema.optional(),
		presetGroupId: z.string().optional(),
		presetType: z.string().optional(),
		spatialTangentIn: z.object({ x: z.number(), y: z.number() }).optional(),
		spatialTangentOut: z.object({ x: z.number(), y: z.number() }).optional(),
	})
	.strict();
export type Keyframe = z.infer<typeof KeyframeSchema>;

export const SignalModeSchema = z.enum(["continuous", "accumulate"]);
export type SignalMode = z.infer<typeof SignalModeSchema>;
/**
 * Which clock a signal track reads: the composition's (default), as audio
 * analysis and shared signals need, or its layer's own, from the layer's
 * start frame, as keyframes do: motion authored for one scene of a sequence.
 */
export const SignalClockSchema = z.enum(["composition", "layer"]);
export type SignalClock = z.infer<typeof SignalClockSchema>;

const RawTrackSourceSchema = z.discriminatedUnion("type", [
	z.object({
		type: z.literal("keyframe"),
	}),
	z.object({
		type: z.literal("signal"),
		inputHandleId: z.string(),
		multiplier: z.number().default(1.0),
		offset: z.number().default(0.0),
		smoothingWindowFrames: z.number().min(0).default(0),
		colorMode: SignalColorModeSchema.optional(),
		colorA: z.string().optional(),
		colorB: z.string().optional(),
		colorThreshold: z.number().optional(),
		signalMode: SignalModeSchema.optional(),
		threshold: z.number().optional(),
		accumulateThreshold: z.number().optional(),
		debounceFrames: z.number().int().min(0).optional(),
		channel: z.string().optional(),
		clock: SignalClockSchema.optional(),
	}),
	z.object({
		type: z.literal("wiggle"),
		frequency: z.number().default(2.0),
		amplitude: z.number().default(50.0),
		octaves: z.number().int().min(1).max(4).default(1),
		seed: z.number().default(1234),
	}),
	z.object({
		type: z.literal("springOvershoot"),
		damping: z.number().default(12),
		stiffness: z.number().default(180),
		mass: z.number().default(1),
	}),
]);

export const TrackSourceSchema = z.preprocess((val: unknown) => {
	if (!val || typeof val !== "object") return val;
	const obj = val as Record<string, unknown>;
	if (obj.type === "signal") {
		const thresh =
			typeof obj.threshold === "number"
				? obj.threshold
				: typeof obj.accumulateThreshold === "number"
					? obj.accumulateThreshold
					: 0.15;
		return {
			type: "signal",
			inputHandleId: obj.inputHandleId ?? obj.handleId,
			multiplier: obj.multiplier ?? obj.amplitude ?? 1.0,
			offset: obj.offset ?? 0.0,
			smoothingWindowFrames: obj.smoothingWindowFrames ?? obj.smoothing ?? 0,
			colorMode: obj.colorMode,
			colorA: obj.colorA,
			colorB: obj.colorB,
			colorThreshold: obj.colorThreshold,
			signalMode: obj.signalMode ?? "continuous",
			threshold: thresh,
			accumulateThreshold: thresh,
			debounceFrames: obj.debounceFrames ?? 2,
			channel: typeof obj.channel === "string" ? obj.channel : "primary",
			...(obj.clock !== undefined && { clock: obj.clock }),
		};
	}
	return val;
}, RawTrackSourceSchema) as unknown as typeof RawTrackSourceSchema;
export type TrackSource = z.infer<typeof RawTrackSourceSchema>;
export type SignalTrackSource = Extract<TrackSource, { type: "signal" }>;

const animationInvariants = (
	anim: {
		tracks?: Array<{
			prop: string;
			source?: { type: string };
			keyframes?: Array<{ value: unknown; frame: number }>;
		}>;
	},
	ctx: z.RefinementCtx,
) => {
	if (!anim?.tracks) return;
	for (let tIdx = 0; tIdx < anim.tracks.length; tIdx++) {
		const track = anim.tracks[tIdx];
		const keyframes = track.keyframes ?? [];

		const isKeyframeSource = !track.source || track.source.type === "keyframe";
		if (isKeyframeSource && keyframes.length < 1) {
			ctx.addIssue({
				code: z.ZodIssueCode.custom,
				message: `Track for property '${track.prop}' must have at least 1 keyframe.`,
				path: ["tracks", tIdx, "keyframes"],
			});
		}

		const isDiscrete = track.prop === "hidden" || track.prop === "muted";
		const isColor =
			track.prop === "fillColor" ||
			track.prop === "strokeColor" ||
			track.prop === "fill" ||
			track.prop === "color";
		// Path morphs key SVG path data.
		const isPath = track.prop === "d";
		for (let kIdx = 0; kIdx < keyframes.length; kIdx++) {
			const kf = keyframes[kIdx];
			if (kIdx > 0) {
				const prevKf = keyframes[kIdx - 1];
				if (kf.frame < prevKf.frame) {
					ctx.addIssue({
						code: z.ZodIssueCode.custom,
						message: "Keyframes must be sorted in ascending order of frame.",
						path: ["tracks", tIdx, "keyframes", kIdx],
					});
				} else if (kf.frame === prevKf.frame) {
					ctx.addIssue({
						code: z.ZodIssueCode.custom,
						message: "Duplicate keyframes at the same frame are not allowed.",
						path: ["tracks", tIdx, "keyframes", kIdx],
					});
				}
			}
			const valType = typeof kf.value;
			if (isDiscrete) {
				if (valType !== "boolean") {
					ctx.addIssue({
						code: z.ZodIssueCode.custom,
						message: `Keyframe value for discrete property '${track.prop}' must be a boolean.`,
						path: ["tracks", tIdx, "keyframes", kIdx, "value"],
					});
				}
			} else if (isColor) {
				if (valType !== "string") {
					ctx.addIssue({
						code: z.ZodIssueCode.custom,
						message: `Keyframe value for color property '${track.prop}' must be a string.`,
						path: ["tracks", tIdx, "keyframes", kIdx, "value"],
					});
				}
			} else if (isPath) {
				if (valType !== "string") {
					ctx.addIssue({
						code: z.ZodIssueCode.custom,
						message: "Keyframe value for 'd' must be SVG path data (a string).",
						path: ["tracks", tIdx, "keyframes", kIdx, "value"],
					});
				}
			} else if (
				valType !== "number" ||
				Number.isNaN(kf.value as number) ||
				!Number.isFinite(kf.value as number)
			) {
				ctx.addIssue({
					code: z.ZodIssueCode.custom,
					message: `Keyframe value for numeric property '${track.prop}' must be a finite number.`,
					path: ["tracks", tIdx, "keyframes", kIdx, "value"],
				});
			} else if (
				(track.prop === "volume" ||
					track.prop === "trimStart" ||
					track.prop === "trimEnd") &&
				((kf.value as number) < 0 || (kf.value as number) > 1)
			) {
				ctx.addIssue({
					code: z.ZodIssueCode.custom,
					message: `Keyframe value for property '${track.prop}' must be between 0 and 1.`,
					path: ["tracks", tIdx, "keyframes", kIdx, "value"],
				});
			}
		}
	}
};

export const AnimationTrackSchema = z
	.object({
		id: z.string().min(1),
		prop: AnimatablePropSchema,
		source: TrackSourceSchema.optional(),
		keyframes: z.array(KeyframeSchema).default([]),
		repeat: z.number().int().optional(),
		yoyo: z.boolean().optional(),
		durationFrames: z.number().int().min(1).optional(),
	})
	.strict();
export type BaseAnimationTrack = z.infer<typeof AnimationTrackSchema>;
export type AnimationTrack<TProp extends AnimatableProp = AnimatableProp> =
	Omit<BaseAnimationTrack, "prop"> & {
		prop: TProp;
	};

export const LayerAnimationSchema = z
	.object({
		tracks: z.array(AnimationTrackSchema).max(24),
		/**
		 * Stepped timing: hold each value for this many frames ("on twos" = 2),
		 * so motion reads hand-animated / stop-motion instead of smooth.
		 */
		frameStep: z.number().int().min(1).max(24).optional(),
	})
	.strict()
	.superRefine(animationInvariants);

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).
// Container `children` fields use z.lazy closures; the union schema is
// cast to z.ZodType<LayoutNode> — the documented pattern (zod-recursion).

export const ToonShadingSchema: z.ZodType<ToonShading> = z
	.object({
		shadowColor: ColorSchema.optional(),
		lightColor: ColorSchema.optional(),
		threshold: z.number().min(-1).max(1).optional(),
		softness: z.number().min(0).max(2).optional(),
		diffuse: z.number().min(0).max(1).optional(),
	})
	.strict();

export const GeometryOutlineOptionsSchema: z.ZodType<GeometryOutlineOptions> = z
	.object({
		color: ColorSchema.optional(),
		width: z.number().min(0).max(32).optional(),
		referenceHeight: z.number().positive().optional(),
		creaseAngle: z.number().min(0).max(180).optional(),
		depthThreshold: z.number().positive().max(1).optional(),
		opacity: z.number().min(0).max(1).optional(),
	})
	.strict();

export const IridescenceConfigSchema = z
	.object({
		intensity: z.number().min(0).max(1).optional(),
		thickness: z.number().min(100).max(1200).optional(),
		ior: z.number().min(1.05).max(2.5).optional(),
	})
	.strict();
export type IridescenceConfig = z.infer<typeof IridescenceConfigSchema>;

export const TriplanarConfigSchema = z
	.object({
		scale: z.number().min(0).optional(),
		sharpness: z.number().min(1).max(16).optional(),
	})
	.strict();
export type TriplanarConfig = z.infer<typeof TriplanarConfigSchema>;

const BaseNodeFields = {
	id: z.string().min(1),
	/** Graph binding — which connected input this node renders (for text/media nodes). */
	inputHandleId: z.string().optional(),
	/** "absolute" = out of flow, placed at x/y of the parent's content box. */
	position: z.enum(["relative", "absolute"]).default("relative"),
	x: z.union([z.number(), z.custom<unknown>()]).default(0),
	y: z.union([z.number(), z.custom<unknown>()]).default(0),
	width: SizeSpecSchema.optional(),
	height: SizeSpecSchema.optional(),
	/** Main-axis leftover share on the parent flex. */
	grow: z.number().min(0).optional(),
	/** Flex shrink factor (Yoga). Defaults to 1 in Yoga when unset. */
	flexShrink: z.number().min(0).optional(),
	/** Flex basis in px (Yoga). */
	flexBasis: z.number().min(0).optional(),
	/** Per-child cross-axis override (Yoga alignSelf). */
	alignSelf: z
		.enum(["auto", "start", "center", "end", "stretch", "baseline"])
		.optional(),
	/** Intrinsic aspect ratio (width / height). */
	aspectRatio: z.number().positive().optional(),
	zIndex: z.number().int().default(0),
	hidden: z.boolean().default(false),
	opacity: z.number().min(0).max(1).default(1),
	blendMode: z.string().optional(),
	/** Per-node WebGPU effect chain (`layer.withEffect(s)`); resolved to operations in to-virtual-media. */
	effects: z.array(EffectSpecSchema).optional(),
	rotation: z.number().default(0),
	scale: z.number().min(0).default(1),
	scaleX: z.number().default(1),
	scaleY: z.number().default(1),
	/** Transform pivot, 0–1 fraction of the node box (0.5 = center). */
	anchorX: z.number().min(0).max(1).default(0.5),
	anchorY: z.number().min(0).max(1).default(0.5),
	/** Clip timing — frames, clip-relative. */
	startFrame: z.number().int().min(0).default(0),
	durationFrames: z.number().int().min(1).optional(),
	/** Directional velocity motion blur shutter angle (0..360, e.g. 180). */
	motionBlurShutter: z.number().min(0).max(360).optional(),
	/** 3D rotation around horizontal X axis in degrees. Range: [-180, 180], default: 0 */
	rotateX: z.number().default(0),
	/** 3D rotation around vertical Y axis in degrees. Range: [-180, 180], default: 0 */
	rotateY: z.number().default(0),
	/** 3D rotation around depth Z axis in degrees. Range: [-360, 360], default: 0 */
	rotateZ: z.number().default(0),
	/** Perspective viewing distance in pixels (0 = orthographic / disabled). */
	perspective: z.number().min(0).default(0),
	/** Perspective origin X anchor (0..1, default 0.5). */
	perspectiveOriginX: z.number().default(0.5),
	/** Perspective origin Y anchor (0..1, default 0.5). */
	perspectiveOriginY: z.number().default(0.5),
	/** Translation along depth Z axis in pixels. */
	translateZ: z.number().default(0),
	/** Backface visibility when rotated > 90deg away from camera. */
	backfaceVisibility: z.enum(["visible", "hidden"]).default("visible"),
	/** Transform rendering style (flat buffer vs shared 3D space). */
	transformStyle: z.enum(["flat", "preserve-3d"]).default("flat"),
	/** Whether this layer lives in unified 3D camera space. */
	is3D: z.boolean().default(false),
	/** 3D position Z in pixels. */
	z: z.union([z.number(), z.custom<unknown>()]).default(0),
	/** 3D scale along Z axis. */
	scaleZ: z.number().default(1.0),
	/** Render both front and back faces in 3D passes. */
	twoSided: z.boolean().default(true),
	/** Material shading mode ("lit" | "unlit" | "glass" | "acrylic" | "frosted" | "metallic"). Default "lit". */
	material: MaterialTypeSchema.default("lit"),
	/** Index of Refraction for glass/acrylic (1.0..3.0, default 1.49). */
	ior: z.number().min(1.0).max(3.0).optional(),
	/** Surface roughness factor [0, 1]. */
	roughness: z.number().min(0).max(1).optional(),
	/** Specular shininess / glossiness exponent for Blinn-Phong shading (default 32.0). */
	shininess: z.number().min(1).max(512).default(32.0),
	/** Specular highlight intensity multiplier [0, 10] (default 0.5). */
	specularIntensity: z.number().min(0).default(0.5),
	/** Metallic factor [0, 1]. */
	metallic: z.number().min(0).max(1).optional(),
	/** Ambient light reflection multiplier [0, 10] (default 1.0). */
	ambientIntensity: z.number().min(0).default(1.0),
	/** Glass transmission transparency factor [0, 1]. */
	transmission: z.number().min(0).max(1).optional(),
	/** Chromatic dispersion coefficient for glass refraction bevels. */
	dispersion: z.number().min(0).max(1.0).optional(),
	/** Fresnel rim grazing highlight power [1, 10]. */
	fresnelPower: z.number().min(1.0).max(10.0).optional(),
	/** Environment reflection intensity [0, 10]. */
	envIntensity: z.number().min(0).max(10.0).optional(),
	/** Light the surface gives off (3D layers): a CSS color added on top of lighting. */
	emissive: ColorSchema.optional(),
	/** Emissive multiplier; above 1 glows past white (feeds bloom). Default 1. */
	emissiveIntensity: z.number().min(0).optional(),
	/** Secondary dielectric clearcoat/varnish lobe 0..1. */
	clearcoat: z.number().min(0).max(1).optional(),
	/** Roughness of the clearcoat layer 0..1 (default 0.08). */
	clearcoatRoughness: z.number().min(0).max(1).optional(),
	/** Anisotropic GGX highlight stretch -1..1. */
	anisotropy: z.number().min(-1).max(1).optional(),
	/** Brush tangent rotation in degrees around the surface normal. */
	anisotropyRotation: z.number().optional(),
	/** Subsurface wrap diffuse and translucent back-scattering 0..1. */
	subsurface: z.number().min(0).max(1).optional(),
	/** Subsurface scatter & transmission tint color. */
	subsurfaceColor: ColorSchema.optional(),
	/** Charlie cloth / velvet grazing retro-reflection lobe 0..1. */
	sheen: z.number().min(0).max(1).optional(),
	/** Cloth sheen tint color. */
	sheenColor: ColorSchema.optional(),
	/** Cloth sheen microfiber roughness 0.05..1 (default 0.5). */
	sheenRoughness: z.number().min(0.05).max(1).optional(),
	/** Thin-film spectral iridescence 0..1 or `{ intensity, thickness, ior }`. */
	iridescence: z
		.union([z.number().min(0).max(1), IridescenceConfigSchema])
		.optional(),
	/** Thin-film thickness in nanometers 100..1200 (default 400). */
	iridescenceThickness: z.number().min(100).max(1200).optional(),
	/** Thin-film refractive index 1.05..2.5 (default 1.3). */
	iridescenceIor: z.number().min(1.05).max(2.5).optional(),
	/** Seamless world-space triplanar texture projection. */
	triplanar: z.union([z.boolean(), TriplanarConfigSchema]).optional(),
	/** World-space triplanar tiling scale. */
	triplanarScale: z.number().min(0).optional(),
	/** World-space triplanar axis blend sharpness 1..16 (default 4). */
	triplanarSharpness: z.number().min(1).max(16).optional(),
	/** Falls into a `castShadow` light's shadow map. Meshes default on, flat layers off. */
	castShadow: z.boolean().optional(),
	/** Art-directed toon lighting, including cast shadows and colored lights. */
	toon: ToonShadingSchema.optional(),
	/** Participate in scene geometry outlines (default true). Excluded surfaces still occlude. */
	outline: z.boolean().optional(),
	/**
	 * Track matte: another layer whose alpha or brightness masks this one.
	 * Laid out like a sibling (same parent), timed with this node; with no
	 * x/y/width/height of its own it covers this node's box.
	 */
	matte: z
		.object({
			node: z.custom<unknown>((v) => typeof v === "object" && v !== null),
			mode: MatteModeSchema.optional(),
		})
		.optional(),
	/** Set by the compiler: the id of this node's hoisted matte layer. */
	matteId: z.string().optional(),
	/** Set by the compiler: this layer is the matte of node `matteOf` (not drawn by itself). */
	matteOf: z.string().optional(),
	matteMode: MatteModeSchema.optional(),
	/**
	 * Relief (3D layers): another layer whose brightness pushes this one's
	 * surface toward the camera, white by `amount` px, along the default
	 * camera's rays, so that lens still sees the flat picture. Laid out and
	 * timed like a matte; drawn flat over this node's box.
	 */
	relief: z
		.object({
			node: z.custom<unknown>((v) => typeof v === "object" && v !== null),
			amount: z.number().optional(),
		})
		.optional(),
	/** Set by the compiler: the id of this node's hoisted relief layer. */
	reliefId: z.string().optional(),
	/** Set by the compiler: this layer is the relief of node `reliefOf` (not drawn by itself). */
	reliefOf: z.string().optional(),
	reliefAmount: z.number().optional(),
	/** Set by the compiler: this layer is the surface texture of model `textureOf` (not drawn by itself). */
	textureOf: z.string().optional(),
	/** Per-node motion: tracks keyed by node id. */
	animation: LayerAnimationSchema.default({ tracks: [] }),
	/** Vision configuration or effect attached directly to the node. */
	vision: z.unknown().optional(),
	/** Relighting configuration attached directly to the node. */
	relighting: z.unknown().optional(),
} as const;

export interface CompositionNodeBase {
	id: string;
	inputHandleId?: string;
	position?: "relative" | "absolute";
	x?: number | unknown;
	y?: number | unknown;
	width?: SizeSpec;
	height?: SizeSpec;
	grow?: number;
	flexShrink?: number;
	flexBasis?: number;
	alignSelf?: "auto" | "start" | "center" | "end" | "stretch" | "baseline";
	aspectRatio?: number;
	zIndex?: number;
	hidden?: boolean;
	opacity?: number;
	blendMode?: string;
	rotation?: number;
	scale?: number;
	scaleX?: number;
	scaleY?: number;
	anchorX?: number;
	anchorY?: number;
	rotateX?: number;
	rotateY?: number;
	rotateZ?: number;
	perspective?: number;
	perspectiveOriginX?: number;
	perspectiveOriginY?: number;
	translateZ?: number;
	backfaceVisibility?: "visible" | "hidden";
	transformStyle?: "flat" | "preserve-3d";
	is3D?: boolean;
	z?: number | unknown;
	scaleZ?: number;
	twoSided?: boolean;
	material?: MaterialType;
	shininess?: number;
	roughness?: number;
	specularIntensity?: number;
	metallic?: number;
	ambientIntensity?: number;
	ior?: number;
	transmission?: number;
	dispersion?: number;
	fresnelPower?: number;
	emissive?: string;
	emissiveIntensity?: number;
	clearcoat?: number;
	clearcoatRoughness?: number;
	anisotropy?: number;
	anisotropyRotation?: number;
	subsurface?: number;
	subsurfaceColor?: string;
	sheen?: number;
	sheenColor?: string;
	sheenRoughness?: number;
	iridescence?: number | IridescenceConfig;
	iridescenceThickness?: number;
	iridescenceIor?: number;
	triplanar?: boolean | TriplanarConfig;
	triplanarScale?: number;
	triplanarSharpness?: number;
	castShadow?: boolean;
	toon?: ToonShading;
	outline?: boolean;
	matte?: { node: unknown; mode?: MatteMode };
	matteId?: string;
	matteOf?: string;
	matteMode?: MatteMode;
	relief?: { node: unknown; amount?: number };
	reliefId?: string;
	reliefOf?: string;
	reliefAmount?: number;
	textureOf?: string;
	envIntensity?: number;
	startFrame?: number;
	durationFrames?: number;
	motionBlurShutter?: number;
	animation?: LayerAnimationSpec;
	/** Attached effect chain. */
	effects?: ProgramEffect[];
	/** Crop options attached directly to the node. */
	crop?: unknown;
	vision?: unknown;
	relighting?: unknown;
}

export interface FlexNode extends CompositionNodeBase {
	kind: "flex";
	dir?: "row" | "column";
	gap?: number;
	padding?: number;
	justify?: "start" | "center" | "end" | "space-between" | "space-around";
	align?: "start" | "center" | "end" | "stretch";
	wrap?: boolean;
	staggerFrames?: number;
	staggerDirection?: "forward" | "reverse" | "center-out";
	overflow?: "visible" | "hidden";
	background?: string;
	borderRadius?: number;
	borderColor?: string;
	borderWidth?: number;
	strokeAlign?: "inside" | "center" | "outside";
	strokeRadius?: number;
	children?: LayoutNode[];
}

export interface BlockNode extends CompositionNodeBase {
	kind: "block";
	gap?: number;
	padding?: number;
	align?: "start" | "center" | "end" | "stretch";
	staggerFrames?: number;
	staggerDirection?: "forward" | "reverse" | "center-out";
	overflow?: "visible" | "hidden";
	background?: string;
	borderRadius?: number;
	borderColor?: string;
	borderWidth?: number;
	strokeAlign?: "inside" | "center" | "outside";
	strokeRadius?: number;
	children?: LayoutNode[];
}

export interface BoxNode extends CompositionNodeBase {
	kind: "box";
	background?: string;
	borderRadius?: number;
	padding?: number;
	staggerFrames?: number;
	staggerDirection?: "forward" | "reverse" | "center-out";
	overflow?: "visible" | "hidden";
	borderColor?: string;
	borderWidth?: number;
	strokeAlign?: "inside" | "center" | "outside";
	strokeRadius?: number;
	children?: LayoutNode[];
}

export const TextShadowSchema = z
	.object({
		color: ColorSchema,
		offset: z
			.object({
				x: z.number(),
				y: z.number(),
			})
			.optional(),
		blurRadius: z.number().min(0).optional(),
	})
	.strict();
export type TextShadow = z.infer<typeof TextShadowSchema>;

export const TextAnimatorTransformSchema = z
	.object({
		x: z.number().optional(),
		y: z.number().optional(),
		scale: z.number().optional(),
		scaleX: z.number().optional(),
		scaleY: z.number().optional(),
		rotation: z.number().optional(),
		rotationX: z.number().optional(),
		rotationY: z.number().optional(),
		opacity: z.number().optional(),
		blur: z.number().optional(),
		color: z.string().optional(),
	})
	.strict();
export type TextAnimatorTransform = z.infer<typeof TextAnimatorTransformSchema>;

export const TextAnimatorSchema = z.object({
	id: z.string(),
	unit: z.enum(["character", "word", "line"]).default("character"),
	rangeStart: z.number().min(0).max(1).default(0),
	rangeEnd: z.number().min(0).max(1).default(1),
	offset: z.number().min(-1).max(1).default(0),
	easing: z.string().default("power2.out"),
	transform: TextAnimatorTransformSchema.optional(),
});
export type TextAnimator = z.infer<typeof TextAnimatorSchema>;

export const TextAnimator = {
	/**
	 * Per-character staggered wave rise with baseline tilt and fade.
	 */
	waveRise(
		options: {
			id?: string;
			unit?: "character" | "word" | "line";
			y?: number;
			rotationX?: number;
			opacity?: number;
			blur?: number;
			easing?: string;
			rangeStart?: number;
			rangeEnd?: number;
			offset?: number;
		} = {},
	): TextAnimator {
		return {
			id: options.id ?? "wave-rise",
			unit: options.unit ?? "character",
			rangeStart: options.rangeStart ?? 0,
			rangeEnd: options.rangeEnd ?? 1,
			offset: options.offset ?? -1,
			easing: options.easing ?? "power2.out",
			transform: {
				y: options.y ?? 40,
				rotationX: options.rotationX ?? 45,
				opacity: options.opacity ?? 0,
				blur: options.blur ?? 0,
			},
		};
	},

	/**
	 * Per-word or per-character pop / scale bounce.
	 */
	wordPop(
		options: { id?: string; scale?: number; y?: number; easing?: string } = {},
	): TextAnimator {
		return {
			id: options.id ?? "word-pop",
			unit: "word",
			rangeStart: 0,
			rangeEnd: 1,
			offset: -1,
			easing: options.easing ?? "back.out(1.6)",
			transform: {
				scale: options.scale ?? 0,
				y: options.y ?? 20,
				opacity: 0,
			},
		};
	},

	/**
	 * Per-character cinematic optical blur to crisp reveal.
	 */
	blurIn(
		options: {
			id?: string;
			unit?: "character" | "word";
			blur?: number;
			y?: number;
			opacity?: number;
			easing?: string;
		} = {},
	): TextAnimator {
		return {
			id: options.id ?? "blur-in",
			unit: options.unit ?? "character",
			rangeStart: 0,
			rangeEnd: 1,
			offset: -1,
			easing: options.easing ?? "power3.out",
			transform: {
				blur: options.blur ?? 16,
				y: options.y ?? 20,
				opacity: options.opacity ?? 0,
			},
		};
	},

	/**
	 * 3D letter flip (like airport split-flap display or 3D letter roll).
	 */
	flip3D(
		options: {
			id?: string;
			unit?: "character" | "word";
			rotationX?: number;
			easing?: string;
		} = {},
	): TextAnimator {
		return {
			id: options.id ?? "flip-3d",
			unit: options.unit ?? "character",
			rangeStart: 0,
			rangeEnd: 1,
			offset: -1,
			easing: options.easing ?? "back.out(1.4)",
			transform: {
				rotationX: options.rotationX ?? 90,
				opacity: 0,
			},
		};
	},

	/**
	 * Color sweep passing across glyphs/words.
	 */
	colorSweep(options: {
		id?: string;
		color: string;
		unit?: "character" | "word";
		easing?: string;
	}): TextAnimator {
		return {
			id: options.id ?? "color-sweep",
			unit: options.unit ?? "character",
			rangeStart: 0,
			rangeEnd: 0.5,
			offset: -0.5,
			easing: options.easing ?? "power2.inOut",
			transform: {
				color: options.color,
			},
		};
	},
};

export interface TextNode extends CompositionNodeBase {
	kind: "text";
	text?: string;
	spans?: TextSpan[];
	fontFamily?: string;
	fontSize?: number;
	fontWeight?: number | string;
	fontStyle?: string;
	/**
	 * Variable font axes by tag, as CSS `font-variation-settings`: `{ wdth: 68 }`
	 * narrows a font with a width axis, `{ opsz: 72 }` or `{ GRAD: 50 }` set
	 * others. `fontWeight` sets `wght`; `opsz` follows the font size unless set.
	 * Axes the font lacks are ignored. Spans inherit them.
	 */
	fontVariations?: Record<string, number>;
	fill?: string;
	align?: "start" | "center" | "end";
	/**
	 * Base direction of each paragraph. "auto" (default) takes it from the
	 * first strong character, so Arabic, Hebrew or Persian reads right to
	 * left; "start"/"end" alignment follows it.
	 */
	direction?: "ltr" | "rtl" | "auto";
	verticalAlign?: "top" | "middle" | "bottom";
	lineHeight?: number;
	letterSpacing?: number;
	background?: string;
	borderRadius?: number;
	padding?: number;
	stroke?: string;
	strokeWidth?: number;
	strokeAlign?: "inside" | "center" | "outside";
	textShadow?: string;
	shadows?: TextShadow[];
	pathOptions?: TextPathOptions;
	typewriter?: TypewriterAnimator;
	marquee?: KineticMarqueeConfig;
	animators?: (TextAnimator | AETextAnimator | AdvancedTextAnimator)[];
}

export interface MediaNode extends CompositionNodeBase {
	kind: "media";
	inputHandleId: string;
	src?: string;
	dataType?: string;
	fit?: "cover" | "contain" | "fill" | "none";
	dpr?: number;
	borderRadius?: number;
	borderColor?: string;
	borderWidth?: number;
	strokeAlign?: "inside" | "center" | "outside";
	strokeRadius?: number;
	volume?: number;
	muted?: boolean;
	/** Source in-point: seconds into the clip that play at the layer's startFrame. */
	trimStartSec?: number;
	/** Layer-local frame to absolute source time mapping. */
	timeRemap?: MediaTimeRemapInput;
	// Caption styling
	fontFamily?: string;
	fontSize?: number;
	fontWeight?: number | string;
	fontStyle?: string;
	fill?: string;
	align?: "start" | "center" | "end";
	/** Caption text direction; see {@link TextNode.direction}. */
	direction?: "ltr" | "rtl" | "auto";
	verticalAlign?: "top" | "middle" | "bottom";
	lineHeight?: number;
	letterSpacing?: number;
	background?: string;
	padding?: number;
	stroke?: string;
	strokeWidth?: number;
	textShadow?: string;
	shadows?: TextShadow[];
	maxWidth?: number;
}

export interface ShapeNode extends CompositionNodeBase {
	kind: "shape";
	shapeType?: ShapeType;
	borderRadius?: number;
	radiusTL?: number;
	radiusTR?: number;
	radiusBR?: number;
	radiusBL?: number;
	polygonSides?: number;
	starPoints?: number;
	starInnerRadiusRatio?: number;
	arrowHeadWidth?: number;
	arrowHeadLength?: number;
	arrowShaftWidth?: number;
	d?: string;
	fillType?: "solid" | "linear" | "radial" | "none";
	fillColor?: string;
	gradientEndColor?: string;
	gradientAngle?: number;
	strokeColor?: string;
	strokeWidth?: number;
	strokeDashArray?: string;
	strokeDashOffset?: number;
	strokeLineCap?: "butt" | "round" | "square";
	strokeLineJoin?: "miter" | "round" | "bevel";
	strokeAlign?: "inside" | "center" | "outside";
	trimStart?: number;
	trimEnd?: number;
	trimOffset?: number;
}

/**
 * The picture a camera draws. `perspective` is an ordinary lens; the others
 * are cube cameras: the scene is drawn as six 90° faces around the eye and
 * remapped, so they can show what no single frustum holds.
 */
export const CameraProjectionSchema = z.enum([
	"perspective",
	"equirectangular",
	"fisheye",
]);
export type CameraProjection = z.infer<typeof CameraProjectionSchema>;

export const CameraLensSchema = z
	.object({
		focalLength: z.number().min(5).max(500).default(50),
		/**
		 * Degrees. Perspective: vertical field of view, up to 160. Fisheye: the
		 * full angle across the frame's height (equidistant), up to 360.
		 * Equirectangular always shows the whole sphere and ignores it.
		 */
		fov: z.number().min(5).max(360).optional(),
		sensorWidth: z.number().default(36),
		near: z.number().min(0.1).default(1),
		far: z.number().min(10).default(50000),
		zoom: z.number().min(0.01).default(1.0),
		projection: CameraProjectionSchema.default("perspective"),
		/**
		 * Cube face size in pixels for cube cameras. Default: matches the
		 * output's sharpness at the centre of the view, up to 4096.
		 */
		cubeSize: z.number().int().min(64).max(8192).optional(),
	})
	.strict();

/** A lens as authored: fields with schema defaults may be left out. */
export type CameraLens = z.input<typeof CameraLensSchema>;

export const CameraDoFSchema = z
	.object({
		enabled: z.boolean().default(false),
		focusDistance: z.number().min(1).default(1000),
		fStop: z.number().min(0.5).max(64).default(2.8),
		maxBlurRadius: z.number().min(0).max(128).default(32),
		apertureBlades: z.number().int().min(0).max(12).default(0),
		anamorphicRatio: z.number().min(0.5).max(3.0).default(1.0),
	})
	.strict();

/** Depth of field as authored: fields with schema defaults may be left out. */
export type CameraDoF = z.input<typeof CameraDoFSchema>;

export const CameraShakeSchema = z
	.object({
		translationAmplitude: z.number().min(0).default(0),
		rotationAmplitude: z.number().min(0).default(0),
		frequency: z.number().min(0.1).max(60).default(2.5),
		octaves: z.number().int().min(1).max(6).default(3),
		seed: z.number().default(42),
	})
	.strict();

export type CameraShake = z.input<typeof CameraShakeSchema>;

/**
 * Per-object shutter motion blur for the 3D scene: every mesh, skinned
 * joint, instance and fractured piece streaks by its own motion over the
 * shutter (and the camera's), reconstructed from a velocity buffer.
 */
export const CameraMotionBlurSchema = z
	.object({
		/** Shutter angle, degrees: 180 is the film look, 360 the whole frame interval. Default 180. */
		shutter: z.number().min(1).max(720).default(180),
		/** Taps along each pixel's motion, 4..64. Default 20. */
		samples: z.number().int().min(4).max(64).default(20),
		/** Longest streak from a pixel, px (also the tile size). Default 48. */
		maxBlur: z.number().min(4).max(160).default(48),
	})
	.strict();

export type CameraMotionBlur = z.input<typeof CameraMotionBlurSchema>;

/**
 * The camera moves through the scene near the speed of light. What it sees
 * is physics, not grading: rays crowd towards the direction of motion
 * (aberration), colours shift blue ahead and red behind (Doppler) and ahead
 * brightens (beaming). Always drawn by a cube camera.
 */
export const CameraRelativitySchema = z
	.object({
		/** β = v / c. Animate it with the `relativitySpeed` prop. */
		speed: z.number().min(0).max(0.9999).default(0),
		/** World-space direction of motion. Default: where the camera looks. */
		direction: z.tuple([z.number(), z.number(), z.number()]).optional(),
		/** Shift colours along the spectrum. Default true. */
		doppler: z.boolean().default(true),
		/** Brighten ahead, dim behind. Default true. */
		beaming: z.boolean().default(true),
		/**
		 * Exposure for the shifted light: "auto" (default) meters the centre of
		 * the view, so what the camera looks at keeps its brightness at rest;
		 * a number is fixed stops (0 = the true, often blinding, brightness).
		 */
		exposure: z
			.union([z.literal("auto"), z.number().min(-64).max(16)])
			.default("auto"),
	})
	.strict();

/** Relativity as authored: fields with schema defaults may be left out. */
export type CameraRelativity = z.input<typeof CameraRelativitySchema>;

export interface CameraNode {
	id: string;
	kind: "camera";
	mode?: "lookAt" | "free" | "orbit";
	x?: number;
	y?: number;
	z?: number;
	targetX?: number;
	targetY?: number;
	targetZ?: number;
	pitch?: number;
	yaw?: number;
	roll?: number;
	lens?: CameraLens;
	dof?: CameraDoF;
	shake?: CameraShake;
	/** Shutter motion blur of the 3D scene; `true` takes the defaults. */
	motionBlur?: boolean | CameraMotionBlur;
	relativity?: CameraRelativity;
	startFrame?: number;
	durationFrames?: number;
	animation?: LayerAnimationSpec;
}

export const CameraNodeSchema: z.ZodType<CameraNode> = z
	.object({
		id: z.string().min(1),
		kind: z.literal("camera"),
		mode: z.enum(["lookAt", "free", "orbit"]).default("lookAt"),
		x: z.number().optional(),
		y: z.number().optional(),
		z: z.number().optional(),
		targetX: z.number().optional(),
		targetY: z.number().optional(),
		targetZ: z.number().optional(),
		pitch: z.number().default(0),
		yaw: z.number().default(0),
		roll: z.number().default(0),
		lens: CameraLensSchema.optional(),
		dof: CameraDoFSchema.optional(),
		shake: CameraShakeSchema.optional(),
		motionBlur: z.union([z.boolean(), CameraMotionBlurSchema]).optional(),
		relativity: CameraRelativitySchema.optional(),
		startFrame: z.number().int().min(0).default(0),
		durationFrames: z.number().int().min(1).optional(),
		animation: LayerAnimationSchema.default({ tracks: [] }),
	})
	.strict() as unknown as z.ZodType<CameraNode>;

export type LightType =
	| "ambient"
	| "directional"
	| "point"
	| "spot"
	| "rect"
	| "environment";
export const LightTypeSchema = z.enum([
	"ambient",
	"directional",
	"point",
	"spot",
	"rect",
	/** Scene world: image-based light, tone mapping, exposure, fog. Turns on physical shading. */
	"environment",
]);

export const EnvironmentPresetSchema = z.enum([
	"studio",
	"soft",
	"warm",
	"sunset",
	"night",
	"neon",
	"neutral",
]);
export type EnvironmentPreset = z.infer<typeof EnvironmentPresetSchema>;

export const ToneMappingSchema = z.enum(["neutral", "agx", "aces", "none"]);
export type ToneMapping = z.infer<typeof ToneMappingSchema>;

export const EnvironmentFogSchema = z
	.object({
		color: ColorSchema,
		start: z.number().min(0),
		end: z.number().min(0),
		opacity: z.number().min(0).max(1).optional(),
	})
	.strict();
export type EnvironmentFog = z.infer<typeof EnvironmentFogSchema>;

export const BloomConfigSchema = z
	.object({
		/** Glow strength. Default 0.2. */
		intensity: z.number().min(0).max(10).optional(),
		/** Scene radiance where glow starts (1 = white). Default 2.5. */
		threshold: z.number().min(0).max(16).optional(),
		/** Soft transition below the threshold. Default 0.4. */
		knee: z.number().min(0).max(1).optional(),
		/** Spread in mip levels (1..8). Default 6. */
		radius: z.number().min(1).max(8).optional(),
	})
	.strict();
export type BloomConfig = z.infer<typeof BloomConfigSchema>;

export const EnvironmentFloorSchema = z
	.object({
		/** World Y coordinate of the floor plane (px, y down). */
		y: z.number(),
		/** Base floor surface color (default "#08070a"). */
		color: ColorSchema.optional(),
		/** Mirror reflectivity at normal incidence / Fresnel scale, 0..1 (default 0.35). */
		reflectivity: z.number().min(0).max(1).optional(),
		/** Surface roughness 0..1: controls anisotropic vertical/horizontal reflection blur (default 0.35). */
		roughness: z.number().min(0).max(1).optional(),
		/** Reflection fade-out distance from the floor plane in world Y px (default 900). */
		fadeDistance: z.number().min(0).optional(),
		/** Optional overall opacity of the floor plane, 0..1 (default 1; 0 draws only additive reflection over background). */
		opacity: z.number().min(0).max(1).optional(),
	})
	.strict();

export type EnvironmentFloor = z.infer<typeof EnvironmentFloorSchema>;

export const EnvironmentVolumetricFogNoiseSchema = z
	.object({
		/** World-space noise frequency (1 / period in px). Default 0.003. */
		scale: z.number().min(0.0001).optional(),
		/** Density modulation depth 0..1. Default 0.45. */
		strength: z.number().min(0).max(1).optional(),
		/** Wind drift velocity [vx, vy, vz] in world px/sec. Default [20, -8, 12]. */
		speed: z.tuple([z.number(), z.number(), z.number()]).optional(),
		/** FBM octaves 1..3. Default 2. */
		octaves: z.number().int().min(1).max(3).optional(),
	})
	.strict();
export type EnvironmentVolumetricFogNoise = z.infer<
	typeof EnvironmentVolumetricFogNoiseSchema
>;

export const EnvironmentVolumetricFogSchema = z
	.object({
		/** Base extinction/scattering density (typical range 0.002..0.15, default 0.02). */
		density: z.number().min(0).optional(),
		/** In-scattering albedo tint (default: environment horizon color). */
		color: ColorSchema.optional(),
		/** Henyey-Greenstein forward/back scatter asymmetry g in (-0.95..0.95). Default 0.55. */
		anisotropy: z.number().min(-0.95).max(0.95).optional(),
		/** Exponential height falloff rate (0 = uniform, >0 = ground mist). Default 0.0015. */
		heightFalloff: z.number().min(0).optional(),
		/** Reference world Y height for ground fog (px, y down). Default 540. */
		baseHeight: z.number().optional(),
		/** Raymarch step count per half-res pixel (8..64, default 28). */
		steps: z.number().int().min(8).max(64).optional(),
		/** Maximum raymarch distance from camera in world px. Default 2800. */
		maxDistance: z.number().min(100).optional(),
		/** Multiplier on direct-light in-scattering / god rays. Default 1.5. */
		lightIntensity: z.number().min(0).optional(),
		/** Multiplier on ambient / sky in-scattering. Default 0.35. */
		ambientIntensity: z.number().min(0).optional(),
		/** Optional 3D procedural FBM turbulence in the fog medium. */
		noise: z
			.union([z.boolean(), EnvironmentVolumetricFogNoiseSchema])
			.optional(),
	})
	.strict();
export type EnvironmentVolumetricFog = z.infer<
	typeof EnvironmentVolumetricFogSchema
>;

export const EnvironmentSsrSchema = z
	.object({
		/** How fully a found reflection replaces the environment's, 0..1. Default 0.85. */
		intensity: z.number().min(0).max(1).optional(),
		/** Roughest surface that traces reflections (0..1). Default 0.6. */
		maxRoughness: z.number().min(0).max(1).optional(),
		/** How far behind a surface, in world px, a ray still counts as hitting it. Default 120. */
		thickness: z.number().min(1).optional(),
		/** Hi-Z march iterations per ray (16..64). Default 32. */
		steps: z.number().int().min(16).max(64).optional(),
	})
	.strict();
export type EnvironmentSsr = z.infer<typeof EnvironmentSsrSchema>;

export const EnvironmentGiSchema = z
	.object({
		/** Strength of the bounced light, 0..4. Default 1. */
		intensity: z.number().min(0).max(4).optional(),
		/** Gather radius in world px. Default 400. */
		radius: z.number().min(1).optional(),
		/** Horizon-scan directions per pixel (4..16). Default 6. */
		samples: z.number().int().min(4).max(16).optional(),
	})
	.strict();
export type EnvironmentGi = z.infer<typeof EnvironmentGiSchema>;

export interface LightNode {
	id: string;
	kind: "light";
	lightType?: LightType;
	color?: string;
	intensity?: number;
	x?: number;
	y?: number;
	z?: number;
	targetX?: number;
	targetY?: number;
	targetZ?: number;
	direction?: [number, number, number];
	radius?: number;
	decay?: number;
	angle?: number;
	penumbra?: number;
	/** Area light width in world px (default 240, rect lights only). */
	width?: number;
	/** Area light height in world px (default 140, rect lights only). */
	height?: number;
	/** Emit from both faces of a rect light (default false). */
	twoSided?: boolean;
	/** Directional / spot / point / rect: render a shadow map. */
	castShadow?: boolean;
	/** Shadow edge blur in shadow-map texels. Default 2.5. */
	shadowSoftness?: number;
	/** 0..1, how dark shadows get. Default 1. */
	shadowDarkness?: number;
	/** Shadow map resolution (texels per side). Default 2048 (1024 for point). */
	shadowMapSize?: number;
	// environment
	preset?: EnvironmentPreset;
	/** Equirectangular panorama for real HDRI IBL: a `.hdr` (Radiance RGBE) or `.exr` (OpenEXR) path, or the file's bytes. */
	hdri?: string | Uint8Array;
	top?: string;
	horizon?: string;
	bottom?: string;
	softboxes?: number;
	rotation?: number;
	exposure?: number;
	toneMapping?: ToneMapping;
	fog?: EnvironmentFog;
	floor?: EnvironmentFloor;
	/** Froxel-style volumetric participating media & shadowed light shafts (god rays). */
	volumetricFog?: boolean | EnvironmentVolumetricFog;
	/** Animatable / signal-driven override for volumetricFog.density. */
	volumetricFogDensity?: number;
	/** Animatable / signal-driven override for volumetricFog.anisotropy. */
	volumetricFogAnisotropy?: number;
	/** Animatable / signal-driven override for volumetricFog.noise.strength. */
	volumetricFogNoiseStrength?: number;
	/** Screen-space reflections of nearby geometry and emissives on glossy surfaces. */
	ssr?: boolean | EnvironmentSsr;
	/** Screen-space diffuse GI: occlusion and color bleeding from visible surfaces. */
	gi?: boolean | EnvironmentGi;
	/** Optional depth/normal outlines, before depth of field and bloom. */
	outlines?: boolean | GeometryOutlineOptions;
	/** Glow around emissive surfaces and hot highlights: `true` or settings. */
	bloom?: boolean | BloomConfig;
	startFrame?: number;
	durationFrames?: number;
	animation?: LayerAnimationSpec;
}

export const LightNodeSchema: z.ZodType<LightNode> = z
	.object({
		id: z.string().min(1),
		kind: z.literal("light"),
		lightType: LightTypeSchema.default("directional"),
		color: ColorSchema.default("#ffffff"),
		intensity: z.number().default(1.0),
		x: z.number().optional(),
		y: z.number().optional(),
		z: z.number().optional(),
		targetX: z.number().optional(),
		targetY: z.number().optional(),
		targetZ: z.number().optional(),
		direction: z.tuple([z.number(), z.number(), z.number()]).optional(),
		radius: z.number().min(0).default(1000),
		decay: z.number().min(0).default(2.0),
		angle: z.number().min(0).max(180).default(45),
		penumbra: z.number().min(0).max(1).default(0.2),
		width: z.number().min(0).optional(),
		height: z.number().min(0).optional(),
		twoSided: z.boolean().optional(),
		castShadow: z.boolean().optional(),
		shadowSoftness: z.number().min(0).max(64).optional(),
		shadowDarkness: z.number().min(0).max(1).optional(),
		shadowMapSize: z.number().int().min(256).max(8192).optional(),
		preset: EnvironmentPresetSchema.optional(),
		hdri: z
			.union([z.string(), z.custom<Uint8Array>((v) => v instanceof Uint8Array)])
			.optional(),
		top: ColorSchema.optional(),
		horizon: ColorSchema.optional(),
		bottom: ColorSchema.optional(),
		softboxes: z.number().min(0).optional(),
		rotation: z.number().optional(),
		exposure: z.number().min(-16).max(16).optional(),
		toneMapping: ToneMappingSchema.optional(),
		fog: EnvironmentFogSchema.optional(),
		floor: EnvironmentFloorSchema.optional(),
		volumetricFog: z
			.union([z.boolean(), EnvironmentVolumetricFogSchema])
			.optional(),
		volumetricFogDensity: z.number().min(0).optional(),
		volumetricFogAnisotropy: z.number().min(-0.95).max(0.95).optional(),
		volumetricFogNoiseStrength: z.number().min(0).max(1).optional(),
		ssr: z.union([z.boolean(), EnvironmentSsrSchema]).optional(),
		gi: z.union([z.boolean(), EnvironmentGiSchema]).optional(),
		outlines: z.union([z.boolean(), GeometryOutlineOptionsSchema]).optional(),
		bloom: z.union([z.boolean(), BloomConfigSchema]).optional(),
		startFrame: z.number().int().min(0).default(0),
		durationFrames: z.number().int().min(1).optional(),
		animation: LayerAnimationSchema.default({ tracks: [] }),
	})
	.strict() as unknown as z.ZodType<LightNode>;

export interface Model3DNode {
	id: string;
	kind: "model3d";
	src?: string;
	modelFormat?:
		| "obj"
		| "fbx"
		| "gltf"
		| "glb"
		| "stl"
		| "ply"
		| "vox"
		| "3ds"
		| "off"
		| "auto";
	modelData?: unknown;
	animationName?: string;
	animationProgress?: number;
	animationTime?: number;
	animationSpeed?: number;
	loop?: boolean;
	x?: number;
	y?: number;
	z?: number;
	rotateX?: number;
	rotateY?: number;
	rotateZ?: number;
	scale?: number;
	scaleX?: number;
	scaleY?: number;
	scaleZ?: number;
	material?: MaterialType;
	shininess?: number;
	roughness?: number;
	specularIntensity?: number;
	ambientIntensity?: number;
	metallic?: number;
	emissive?: string;
	emissiveIntensity?: number;
	clearcoat?: number;
	clearcoatRoughness?: number;
	anisotropy?: number;
	anisotropyRotation?: number;
	subsurface?: number;
	subsurfaceColor?: string;
	sheen?: number;
	sheenColor?: string;
	sheenRoughness?: number;
	iridescence?: number | IridescenceConfig;
	iridescenceThickness?: number;
	iridescenceIor?: number;
	triplanar?: boolean | TriplanarConfig;
	triplanarScale?: number;
	triplanarSharpness?: number;
	toon?: ToonShading;
	outline?: boolean;
	castShadow?: boolean;
	color?: string;
	colorTint?: string;
	opacity?: number;
	twoSided?: boolean;
	wireframe?: boolean;
	is3D?: boolean;
	texture?: string;
	center?: boolean;
	normalizeSize?: number;
	startFrame?: number;
	durationFrames?: number;
	animation?: LayerAnimationSpec;
	audioDeform?: MeshAudioDeformConfig;
	text3dOptions?: unknown;
	/** Layer3D primitive options (roundedBox, sphere, cylinder, shard) the mesh is rebuilt from when modelData is lost. */
	primitive3d?: unknown;
	/** Layer3D.instances hardware-instancing options. */
	instances3d?: unknown;
	/** Layer3D.swarm GPU simulation and instancing options. */
	swarm3d?: unknown;
	/** Layer3D.scatter: instances placed on another model's surface. */
	scatter3d?: Scatter3DSpec;
	/** Voronoi destruction: the mesh drawn as pieces posed by physics (`world.fracture`). */
	fracture3d?: Fracture3DSpec;
	/** Procedural wind sway (bends vertices downwind by height above the mesh base). */
	wind?: WindConfig;
	/** Any layer (image, video, layout) drawn each frame and wrapped onto the mesh by its UVs. */
	textureLayer?: { node: unknown };
	/** Set by the compiler: the id of the hoisted texture layer. */
	textureLayerId?: string;
	/** Clips blended in order, each over the pose beneath by its weight (replaces animationName). */
	animationLayers?: ModelAnimationLayer[];
	/** Two-bone IK: limbs reach scene-space targets. */
	ik?: TwoBoneIkConstraint[];
	/** Joints (heads, eyes) turn toward scene-space targets. */
	lookAt?: LookAtConstraint[];
	/** Secondary motion simulated from frame 0 (capes, tails, hair). */
	springBones?: SpringBoneChain[];
	/** Joints posed directly by name (local Euler degrees, offsets), over the clips. */
	pose?: Record<string, JointPose>;
	/**
	 * Blend shape weights by target name (glTF `extras.targetNames`; case is
	 * ignored): `{ eyeBlinkLeft: blink, jawOpen: speech }`. Each value is a
	 * number, `[[frame, v]]` keys, `(frame) => v` or a signal; it replaces the
	 * clip's weight for that target.
	 */
	morphs?: Record<string, NumberTrack>;
	/** Bones pointed along scene directions, parents first (pose retargeting). */
	aim?: AimConstraint[];
	/** Joints driven by other joints, on top of any the model file declares (eyelids, twist bones). */
	drive?: JointDriver[];
	/** Instance nodes: every instance a skinned character on its own clip, phase and speed. */
	crowd?: CrowdConfig;
}

export type LayoutNode =
	| FlexNode
	| BlockNode
	| BoxNode
	| TextNode
	| MediaNode
	| ShapeNode
	| CameraNode
	| LightNode
	| Model3DNode;

export const containerChildren = (): z.ZodType<LayoutNode[]> =>
	z.array(z.lazy((): z.ZodType<LayoutNode> => LayoutNodeSchema));

export const FlexNodeSchema: z.ZodType<FlexNode> = z
	.object({
		...BaseNodeFields,
		kind: z.literal("flex"),
		dir: z.enum(["row", "column"]).default("row"),
		gap: z.number().min(0).default(0),
		padding: z.number().min(0).default(0),
		justify: z
			.enum(["start", "center", "end", "space-between", "space-around"])
			.default("start"),
		align: z.enum(["start", "center", "end", "stretch"]).default("start"),
		wrap: z.boolean().default(false),
		staggerFrames: z.number().min(0).default(0),
		staggerDirection: z
			.enum(["forward", "reverse", "center-out"])
			.default("forward"),
		overflow: z.enum(["visible", "hidden"]).default("visible"),
		background: ColorSchema.optional(),
		borderRadius: z.number().min(0).optional(),
		borderColor: ColorSchema.optional(),
		borderWidth: z.number().min(0).optional(),
		strokeAlign: z.enum(["inside", "center", "outside"]).optional(),
		strokeRadius: z.number().min(0).optional(),
		children: containerChildren().optional(),
	})
	.strict() as unknown as z.ZodType<FlexNode>;

export const BlockNodeSchema: z.ZodType<BlockNode> = z
	.object({
		...BaseNodeFields,
		kind: z.literal("block"),
		gap: z.number().min(0).default(0),
		padding: z.number().min(0).default(0),
		align: z.enum(["start", "center", "end", "stretch"]).default("start"),
		staggerFrames: z.number().min(0).default(0),
		staggerDirection: z
			.enum(["forward", "reverse", "center-out"])
			.default("forward"),
		overflow: z.enum(["visible", "hidden"]).default("visible"),
		background: ColorSchema.optional(),
		borderRadius: z.number().min(0).optional(),
		borderColor: ColorSchema.optional(),
		borderWidth: z.number().min(0).optional(),
		strokeAlign: z.enum(["inside", "center", "outside"]).optional(),
		strokeRadius: z.number().min(0).optional(),
		children: containerChildren().optional(),
	})
	.strict() as unknown as z.ZodType<BlockNode>;

export const BoxNodeSchema: z.ZodType<BoxNode> = z
	.object({
		...BaseNodeFields,
		kind: z.literal("box"),
		/** Fill color of the rectangle (DSL `fill:` on box). */
		background: ColorSchema,
		borderRadius: z.number().min(0).optional(),
		padding: z.number().min(0).default(0),
		staggerFrames: z.number().min(0).default(0),
		staggerDirection: z
			.enum(["forward", "reverse", "center-out"])
			.default("forward"),
		overflow: z.enum(["visible", "hidden"]).default("visible"),
		borderColor: ColorSchema.optional(),
		borderWidth: z.number().min(0).optional(),
		strokeAlign: z.enum(["inside", "center", "outside"]).optional(),
		strokeRadius: z.number().min(0).optional(),
		children: containerChildren().optional(),
	})
	.strict() as unknown as z.ZodType<BoxNode>;

export const TextSpanMarkSchema = z
	.object({
		background: ColorSchema,
		borderRadius: z.number().min(0).optional(),
		paddingX: z.number().min(0).optional(),
		paddingY: z.number().min(0).optional(),
	})
	.strict();

export const TextSpanSchema = z
	.object({
		text: z.union([
			z.string(),
			z.custom<{ get: (ctx?: unknown) => string }>((v) =>
				Boolean(v && typeof v === "object" && "get" in v),
			),
		]),
		fontFamily: z.string().optional(),
		fontSize: z
			.union([
				z.number().positive(),
				z.custom<{ get: (ctx?: unknown) => number }>((v) =>
					Boolean(v && typeof v === "object" && "get" in v),
				),
			])
			.optional(),
		fontWeight: z.union([z.number().int(), z.string()]).optional(),
		fontStyle: z.enum(["normal", "italic"]).optional(),
		fill: z
			.union([
				ColorSchema,
				z.custom<{ get: (ctx?: unknown) => string }>((v) =>
					Boolean(v && typeof v === "object" && "get" in v),
				),
			])
			.optional(),
		letterSpacing: z.number().optional(),
		baselineShift: z.number().optional(),
		opacity: z
			.union([
				z.number().min(0).max(1),
				z.custom<{ get: (ctx?: unknown) => number }>((v) =>
					Boolean(v && typeof v === "object" && "get" in v),
				),
			])
			.optional(),
		mark: TextSpanMarkSchema.optional(),
	})
	.strict();

const TextFields = {
	text: z.string().default(""),
	spans: z.array(TextSpanSchema).optional(),
	fontFamily: z.string().optional(),
	fontSize: z.number().positive().optional(),
	fontWeight: z.union([z.number().int(), z.string()]).optional(),
	fontStyle: z.string().optional(),
	fontVariations: z.record(z.string(), z.number()).optional(),
	/** Text color (v1 name kept). */
	fill: ColorSchema,
	align: z.enum(["start", "center", "end"]).optional(),
	direction: z.enum(["ltr", "rtl", "auto"]).optional(),
	verticalAlign: z.enum(["top", "middle", "bottom"]).optional(),
	lineHeight: z.number().positive().optional(),
	letterSpacing: z.number().optional(),
	background: ColorSchema,
	borderRadius: z.number().min(0).optional(),
	padding: z.number().min(0).optional(),
	stroke: ColorSchema,
	strokeWidth: z.number().min(0).optional(),
	strokeAlign: z.enum(["inside", "center", "outside"]).optional(),
	textShadow: z.string().optional(),
	shadows: z.array(TextShadowSchema).optional(),
	pathOptions: TextPathOptionsSchema.optional(),
	typewriter: TypewriterAnimatorSchema.optional(),
	marquee: KineticMarqueeConfigSchema.optional(),
	animators: z
		.array(
			z.union([
				TextAnimatorSchema,
				AETextAnimatorSchema,
				AdvancedTextAnimatorSchema,
			]),
		)
		.optional(),
} as const;

export const TextNodeSchema: z.ZodType<TextNode> = z
	.object({
		...BaseNodeFields,
		...TextFields,
		kind: z.literal("text"),
	})
	.strict() as unknown as z.ZodType<TextNode>;

export const MediaNodeSchema: z.ZodType<MediaNode> = z
	.object({
		...BaseNodeFields,
		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(),
		borderRadius: z.number().min(0).optional(),
		borderColor: ColorSchema.optional(),
		borderWidth: z.number().min(0).optional(),
		strokeAlign: z.enum(["inside", "center", "outside"]).optional(),
		strokeRadius: z.number().min(0).optional(),
		volume: z.number().min(0).max(1).default(1),
		muted: z.boolean().default(false),
		trimStartSec: z.number().min(0).optional(),
		timeRemap: MediaTimeRemapInputSchema.optional(),
		// Caption styling
		fontFamily: z.string().optional(),
		fontSize: z.number().positive().optional(),
		fontWeight: z.union([z.number().int(), z.string()]).optional(),
		fontStyle: z.string().optional(),
		fill: ColorSchema,
		align: z.enum(["start", "center", "end"]).optional(),
		direction: z.enum(["ltr", "rtl", "auto"]).optional(),
		verticalAlign: z.enum(["top", "middle", "bottom"]).optional(),
		lineHeight: z.number().positive().optional(),
		letterSpacing: z.number().optional(),
		background: ColorSchema,
		padding: z.number().min(0).optional(),
		stroke: ColorSchema,
		strokeWidth: z.number().min(0).optional(),
		textShadow: z.string().optional(),
		shadows: z.array(TextShadowSchema).optional(),
		maxWidth: z.number().optional(),
	})
	.strict()
	.superRefine((node, ctx) => {
		if (!node.timeRemap) return;
		if (node.trimStartSec !== undefined)
			ctx.addIssue({
				code: "custom",
				path: ["timeRemap"],
				message: "timeRemap cannot be combined with trimStartSec",
			});
		if (node.dataType !== "Video" && node.dataType !== "Audio")
			ctx.addIssue({
				code: "custom",
				path: ["timeRemap"],
				message: "timeRemap requires video or audio media",
			});
		const error = validateMediaTimeRemap(
			node.timeRemap,
			node.durationFrames ?? 0,
		);
		if (error)
			ctx.addIssue({ code: "custom", path: ["timeRemap"], message: error });
	}) as unknown as z.ZodType<MediaNode>;

export const ShapeFields = {
	shapeType: ShapeTypeSchema.default("rect"),
	borderRadius: z.number().min(0).optional(),
	radiusTL: z.number().min(0).optional(),
	radiusTR: z.number().min(0).optional(),
	radiusBR: z.number().min(0).optional(),
	radiusBL: z.number().min(0).optional(),
	polygonSides: z.number().int().min(3).max(64).optional(),
	starPoints: z.number().int().min(3).max(64).optional(),
	starInnerRadiusRatio: z.number().min(0.01).max(0.99).optional(),
	arrowHeadWidth: z.number().min(0).optional(),
	arrowHeadLength: z.number().min(0).optional(),
	arrowShaftWidth: z.number().min(1).optional(),
	d: z.string().optional(),
	fillType: z.enum(["solid", "linear", "radial", "none"]).default("solid"),
	fillColor: ColorSchema.default("#3b82f6"),
	gradientEndColor: ColorSchema.optional(),
	gradientAngle: z.number().default(0),
	strokeColor: ColorSchema.default("#ffffff"),
	strokeWidth: z.number().min(0).default(0),
	strokeDashArray: z.string().optional(),
	strokeDashOffset: z.number().default(0),
	strokeLineCap: z.enum(["butt", "round", "square"]).default("round"),
	strokeLineJoin: z.enum(["miter", "round", "bevel"]).default("round"),
	strokeAlign: z.enum(["inside", "center", "outside"]).optional(),
	trimStart: z.number().min(0).max(1).default(0),
	trimEnd: z.number().min(0).max(1).default(1),
	trimOffset: z.number().default(0),
} as const;

export const ShapeNodeSchema: z.ZodType<ShapeNode> = z
	.object({
		...BaseNodeFields,
		...ShapeFields,
		kind: z.literal("shape"),
	})
	.strict() as unknown as z.ZodType<ShapeNode>;

export const ColorStopSchema = z.object({
	offset: z.number().min(0).max(1),
	color: z.string(),
});
export type ColorStop = z.infer<typeof ColorStopSchema>;

export const Model3DNodeSchema: z.ZodType<Model3DNode> = z
	.object({
		...BaseNodeFields,
		kind: z.literal("model3d"),
		src: z.string().default(""),
		modelFormat: z
			.enum([
				"obj",
				"fbx",
				"gltf",
				"glb",
				"stl",
				"ply",
				"vox",
				"3ds",
				"off",
				"auto",
			])
			.default("auto"),
		modelData: z.unknown().optional(),
		animationName: z.string().optional(),
		animationProgress: z.number().min(0).max(1).default(0),
		animationTime: z.number().min(0).default(0),
		animationSpeed: z.number().default(1.0),
		loop: z.boolean().default(true),
		wireframe: z.boolean().default(false),
		texture: z.string().optional(),
		center: z.boolean().optional(),
		normalizeSize: z.number().optional(),
		scaleX: z.number().default(1.0),
		scaleY: z.number().default(1.0),
		audioDeform: z.record(z.string(), z.unknown()).optional(),
		/** Multiplies the model's material colors (animatable as `color`). */
		color: ColorSchema.optional(),
		colorTint: ColorSchema.optional(),
		text3dOptions: z.unknown().optional(),
		primitive3d: Primitive3DSpecSchema.optional(),
		instances3d: z.unknown().optional(),
		swarm3d: z.unknown().optional(),
		scatter3d: Scatter3DSchema.optional(),
		fracture3d: Fracture3DSchema.optional(),
		wind: WindSchema.optional(),
		textureLayer: TextureLayerSchema.optional(),
		textureLayerId: z.string().optional(),
		animationLayers: z.array(ModelAnimationLayerSchema).optional(),
		ik: z.array(TwoBoneIkSchema).optional(),
		lookAt: z.array(LookAtSchema).optional(),
		springBones: z.array(SpringBoneChainSchema).optional(),
		pose: z.record(z.string(), JointPoseSchema).optional(),
		morphs: z.record(z.string(), NumberTrackSchema).optional(),
		aim: z.array(AimSchema).optional(),
		drive: z.array(JointDriverSchema).optional(),
		crowd: CrowdSchema.optional(),
	})
	.strict() as unknown as z.ZodType<Model3DNode>;

/**
 * Dispatch on `kind`, not a plain union: a plain union tries every member,
 * and each member parses `children` before failing, so parse time grows
 * ~3x per nesting level (a depth-14 tree took minutes). The node schemas
 * are typed `ZodType<…>` for their recursive types, but each is a strict
 * object with a `kind` literal, which is all `discriminatedUnion` reads.
 */
export const LayoutNodeSchema = z.lazy(() =>
	z.discriminatedUnion("kind", [
		FlexNodeSchema,
		BlockNodeSchema,
		BoxNodeSchema,
		TextNodeSchema,
		MediaNodeSchema,
		ShapeNodeSchema,
		CameraNodeSchema,
		LightNodeSchema,
		Model3DNodeSchema,
	] as unknown as [z.ZodObject, ...z.ZodObject[]]),
) as unknown as z.ZodType<LayoutNode>;

// ── the program document ──────────────────────────────────────────────

export const CompositorProgramSchema = z
	.object({
		width: z.number().int().min(1).max(4096),
		height: z.number().int().min(1).max(4096),
		backgroundColor: ColorSchema,
		volume: z.number().min(0).max(1).default(1),
		fps: z.number().int().min(1).max(120).default(24),
		mode: z.enum(["Video", "Image"]).default("Video"),
		/**
		 * Multisample the 3D pass (4 samples per pixel) so mesh edges are smooth.
		 * Default true; false saves the extra target memory (~60-125 MB at 1080p).
		 */
		antialias3d: z.boolean().optional(),
		layout: z.array(LayoutNodeSchema).default([]),
		fonts: z.array(z.string()).optional(),
		signals: z.record(z.string(), z.unknown()).optional(),
		/** Composition-wide effect chain (`comp.apply(effect)`); resolved to operations downstream. */
		effects: z.array(EffectSpecSchema).optional(),
		/** Composition-wide vision config or bundle. */
		vision: z.unknown().optional(),
		/** Per-frame notification hook. */
		onRequestFrame: z.custom<unknown>().optional(),
	})
	.strict();

export type CompositorProgramConfig = z.infer<typeof CompositorProgramSchema>;