Code-first video & image, rendered natively on WebGPU.
/**
* 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>;