Skip to content

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

10.2 KB
Raw Blame
/**
 * Coded validation for the v2 program document (spec: SKILL.md).
 *
 * Runs on the RAW input BEFORE zod: zod strips unknown keys silently, so
 * v1 shapes (`layers`, `layerUpdates`, `FPS`) and structural errors must be
 * caught in a pre-parse walk or the E-codes never fire. The zod schema then
 * handles shape/refinement errors (mapped to E1xxx-style issues).
 */
import {
	type CompositorProgramConfig,
	CompositorProgramSchema,
	type LayoutNode,
} from "./schema.js";

export interface ProgramIssue {
	code: string;
	path: (string | number)[];
	message: string;
}

export type ProgramValidationResult =
	| { ok: true }
	| { ok: false; issues: ProgramIssue[] };

const KIND_SET = new Set([
	"flex",
	"block",
	"box",
	"text",
	"media",
	"shape",
]);
const MAX_NODES = 512;
const MAX_DEPTH = 64;

const issue = (
	code: string,
	path: (string | number)[],
	message: string,
): ProgramIssue => ({ code, path, message });

export function validateLayoutProgram(raw: unknown): ProgramValidationResult {
	const issues: ProgramIssue[] = [];

	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
		return {
			ok: false,
			issues: [issue("E1001", [], "Compositor config must be an object.")],
		};
	}
	const obj = raw as Record<string, unknown>;

	// v1 shapes die here (no backwards compatibility).
	if ("layers" in obj) {
		issues.push(
			issue(
				"E1001",
				["layers"],
				"Config v2 uses `layout` — `layers` is removed.",
			),
		);
	}
	if ("layerUpdates" in obj) {
		issues.push(
			issue(
				"E1001",
				["layerUpdates"],
				"Config v2 uses `layout` — `layerUpdates` is removed.",
			),
		);
	}
	if ("FPS" in obj) {
		issues.push(
			issue("E1001", ["FPS"], "Config v2 uses `fps` — `FPS` is removed."),
		);
	}

	const seenIds = new Set<string>();
	let nodeCount = 0;
	const isImageMode = obj.mode === "Image";

	const walk = (node: unknown, path: (string | number)[], depth: number) => {
		if (depth > MAX_DEPTH) {
			issues.push(
				issue(
					"E1212",
					[...path, "children"],
					`Layout nesting exceeds ${MAX_DEPTH} levels.`,
				),
			);
			return;
		}
		if (!node || typeof node !== "object" || Array.isArray(node)) {
			issues.push(issue("E1201", path, "Layout node must be an object."));
			return;
		}
		nodeCount += 1;
		if (nodeCount > MAX_NODES) {
			issues.push(
				issue("E1211", path, `Composition exceeds ${MAX_NODES} nodes.`),
			);
			return;
		}

		const n = node as Record<string, unknown>;
		const kind = n.kind;

		if (typeof kind !== "string" || !KIND_SET.has(kind)) {
			issues.push(
				issue(
					"E1201",
					[...path, "kind"],
					`Unknown layout node kind '${String(kind)}'. Expected one of: flex, block, box, text, media, shape.`,
				),
			);
		}

		const id = n.id;
		if (typeof id !== "string" || id.length === 0) {
			issues.push(
				issue(
					"E1203",
					[...path, "id"],
					"Layout node requires a non-empty `id`.",
				),
			);
		} else if (seenIds.has(id)) {
			issues.push(
				issue("E1202", [...path, "id"], `Duplicate node id '${id}'.`),
			);
		} else {
			seenIds.add(id);
		}

		// SizeSpec sanity: numeric sizes must be finite and >= 0.
		for (const axis of ["width", "height"] as const) {
			const v = n[axis];
			if (typeof v === "number" && (!Number.isFinite(v) || v < 0)) {
				issues.push(
					issue(
						"E1205",
						[...path, axis],
						`SizeSpec must be a finite number >= 0 or one of "auto" | "fit" | "fill".`,
					),
				);
			} else if (
				typeof v === "string" &&
				v !== "auto" &&
				v !== "fit" &&
				v !== "fill"
			) {
				issues.push(
					issue(
						"E1205",
						[...path, axis],
						`SizeSpec must be a finite number >= 0 or one of "auto" | "fit" | "fill".`,
					),
				);
			}
		}

		const position = n.position;
		const isAbsolute = position === "absolute";
		if (isAbsolute) {
			if (typeof n.x !== "number" || typeof n.y !== "number") {
				issues.push(
					issue(
						"E1206",
						[...path],
						"An absolute node requires numeric `x` and `y`.",
					),
				);
			}
			if (n.grow !== undefined) {
				issues.push(
					issue(
						"E1209",
						[...path, "grow"],
						"`grow` is not allowed on an absolute node (it is out of flow).",
					),
				);
			}
		}

		if (
			kind === "media" &&
			(typeof n.inputHandleId !== "string" || n.inputHandleId.length === 0)
		) {
			issues.push(
				issue(
					"E1204",
					[...path, "inputHandleId"],
					"A media node requires a non-empty `inputHandleId`.",
				),
			);
		}

		if (kind === "text" && typeof n.fontSize === "number" && n.fontSize <= 0) {
			issues.push(
				issue(
					"E1210",
					[...path, "fontSize"],
					"A text node requires fontSize > 0.",
				),
			);
		}

		if (kind === "shape") {
			if (n.trimStart !== undefined) {
				const ts = n.trimStart;
				if (
					typeof ts !== "number" ||
					!Number.isFinite(ts) ||
					Number.isNaN(ts) ||
					ts < 0 ||
					ts > 1
				) {
					issues.push(
						issue(
							"E1208",
							[...path, "trimStart"],
							"`trimStart` must be a finite number between 0 and 1.",
						),
					);
				}
			}
			if (n.trimEnd !== undefined) {
				const te = n.trimEnd;
				if (
					typeof te !== "number" ||
					!Number.isFinite(te) ||
					Number.isNaN(te) ||
					te < 0 ||
					te > 1
				) {
					issues.push(
						issue(
							"E1208",
							[...path, "trimEnd"],
							"`trimEnd` must be a finite number between 0 and 1.",
						),
					);
				}
			}
		}

		// Timing fields only apply to Video mode; Image mode ignores duration/startFrame.
		if (!isImageMode) {
			if (n.durationFrames !== undefined) {
				const df = n.durationFrames;
				if (
					typeof df !== "number" ||
					!Number.isFinite(df) ||
					Number.isNaN(df) ||
					df < 1 ||
					!Number.isInteger(df)
				) {
					issues.push(
						issue(
							"E1207",
							[...path, "durationFrames"],
							`\`durationFrames\` must be a positive integer (>= 1). Received: ${String(df)}.`,
						),
					);
				}
			}

			if (n.startFrame !== undefined) {
				const sf = n.startFrame;
				if (
					typeof sf !== "number" ||
					!Number.isFinite(sf) ||
					Number.isNaN(sf) ||
					sf < 0 ||
					!Number.isInteger(sf)
				) {
					issues.push(
						issue(
							"E1207",
							[...path, "startFrame"],
							`\`startFrame\` must be a non-negative integer (>= 0). Received: ${String(sf)}.`,
						),
					);
				}
			}
		}

		if (n.opacity !== undefined) {
			const op = n.opacity;
			if (
				typeof op !== "number" ||
				!Number.isFinite(op) ||
				Number.isNaN(op) ||
				op < 0 ||
				op > 1
			) {
				issues.push(
					issue(
						"E1213",
						[...path, "opacity"],
						`\`opacity\` must be a number between 0 and 1. Received: ${String(op)}.`,
					),
				);
			}
		}

		// duplicate (id, prop) tracks
		const anim = n.animation as
			| { tracks?: Array<{ prop?: unknown }> }
			| undefined;
		if (anim && Array.isArray(anim.tracks) && kind !== undefined) {
			const props = new Set<string>();
			for (let tIdx = 0; tIdx < anim.tracks.length; tIdx++) {
				const prop = anim.tracks[tIdx]?.prop;
				if (typeof prop === "string") {
					if (props.has(prop)) {
						issues.push(
							issue(
								"E1208",
								[...path, "animation", "tracks", tIdx],
								`Duplicate track property '${prop}' on node '${String(id)}'.`,
							),
						);
					}
					props.add(prop);
				}
			}
		}

		// recurse into children
		const children = n.children;
		if (Array.isArray(children)) {
			for (let i = 0; i < children.length; i++) {
				walk(children[i], [...path, "children", i], depth + 1);
			}
		}
	};

	const layout = obj.layout;
	if (Array.isArray(layout)) {
		for (let i = 0; i < layout.length; i++) {
			walk(layout[i], ["layout", i], 0);
		}
	} else if (layout !== undefined) {
		issues.push(
			issue("E1001", ["layout"], "`layout` must be an array of nodes."),
		);
	}

	if (issues.length > 0) return { ok: false, issues };
	return { ok: true };
}

function cleanImageModeTiming(raw: unknown): unknown {
	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return raw;
	const obj = raw as Record<string, unknown>;
	if (obj.mode !== "Image" || !Array.isArray(obj.layout)) return raw;

	const sanitizeNode = (node: unknown): unknown => {
		if (!node || typeof node !== "object" || Array.isArray(node)) return node;
		const n = { ...(node as Record<string, unknown>) };
		if (
			n.durationFrames !== undefined &&
			(typeof n.durationFrames !== "number" ||
				!Number.isFinite(n.durationFrames) ||
				n.durationFrames < 1 ||
				!Number.isInteger(n.durationFrames))
		) {
			delete n.durationFrames;
		}
		if (
			n.startFrame !== undefined &&
			(typeof n.startFrame !== "number" ||
				!Number.isFinite(n.startFrame) ||
				n.startFrame < 0 ||
				!Number.isInteger(n.startFrame))
		) {
			delete n.startFrame;
		}
		if (Array.isArray(n.children)) {
			n.children = n.children.map(sanitizeNode);
		}
		return n;
	};

	return {
		...obj,
		layout: obj.layout.map(sanitizeNode),
	};
}

/** Fast-fail shape gate used by processors: validate raw config then parse. */
export function parseProgram(raw: unknown): {
	ok: boolean;
	issues?: ProgramIssue[];
	config?: CompositorProgramConfig;
} {
	const pre = validateLayoutProgram(raw);
	if (!pre.ok) return { ok: false, issues: pre.issues };

	const cleaned = cleanImageModeTiming(raw);
	const parsed = CompositorProgramSchema.safeParse(cleaned);
	if (!parsed.success) {
		return {
			ok: false,
			issues: parsed.error.issues.map((i) =>
				issue(
					"E1001",
					i.path.map((p) => (typeof p === "symbol" ? p.toString() : p)),
					i.message,
				),
			),
		};
	}
	return { ok: true, config: parsed.data };
}

/** Collect every node id in the tree (depth-first, in order). */
export function collectNodeIds(nodes: LayoutNode[]): string[] {
	const ids: string[] = [];
	const walk = (n: LayoutNode) => {
		ids.push(n.id);
		if ("children" in n && n.children) walkChildren(n.children);
	};
	const walkChildren = (list: LayoutNode[]) => {
		for (const n of list) walk(n);
	};
	walkChildren(nodes);
	return ids;
}

/** Collect media node bindings: inputHandleId -> node id. */
export function collectMediaBindings(nodes: LayoutNode[]): Map<string, string> {
	const bindings = new Map<string, string>();
	const walk = (n: LayoutNode) => {
		if (n.kind === "media") bindings.set(n.inputHandleId, n.id);
		if ("children" in n && n.children) {
			for (const c of n.children) walk(c);
		}
	};
	for (const n of nodes) walk(n);
	return bindings;
}