Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor
import { validateRig } from '../rig/validate.ts';
import type { Rig } from '../rig/types';
import { parseManifest } from './manifest.ts';
type FileData = Uint8Array | { size: number };
const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === 'object' && !Array.isArray(value);
const numbers = (value: unknown, length: number): value is number[] => Array.isArray(value)
&& value.length === length && value.every(n => typeof n === 'number' && Number.isFinite(n));
const own = (value: object, key: string) => Object.hasOwn(value, key);
/** Validate folder metadata and required files without decoding images or performing I/O. */
export function validateAvatarFiles(files: Record<string, FileData>): string[] {
const errors: string[] = [];
function json(path: string, required = true): Record<string, unknown> | undefined {
if (!own(files, path)) {
if (required) errors.push(`${path}: missing file`);
return;
}
const data = files[path];
if (!(data instanceof Uint8Array)) { errors.push(`${path}: JSON bytes are required`); return; }
let value: unknown;
try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(data)); }
catch { errors.push(`${path}: invalid UTF-8 JSON`); return; }
if (!object(value)) { errors.push(`${path}: expected an object`); return; }
return value;
}
function version(value: Record<string, unknown>, path: string, legacy = true): boolean {
if (value.version === 1 || (legacy && value.version === undefined)) return true;
errors.push(`${path}.version: unsupported version ${JSON.stringify(value.version) ?? 'missing'} (expected 1)`);
return false;
}
function image(path: string) {
if (!own(files, path)) { errors.push(`${path}: missing file`); return; }
const data = files[path], size = data instanceof Uint8Array ? data.byteLength : data?.size;
if (!Number.isSafeInteger(size) || size <= 0) errors.push(`${path}: expected a non-empty file`);
}
function layers(value: unknown, path: string, directory: string, size?: number[]) {
if (!object(value)) { errors.push(`${path}.layers: expected a layer rectangle map`); return; }
for (const [name, rect] of Object.entries(value)) {
const field = `${path}.layers.${name}`;
if (!/^[A-Za-z0-9_-]+$/.test(name)) {
errors.push(`${field}: expected a safe layer name (letters, digits, hyphens or underscores)`);
continue;
}
if (!numbers(rect, 4) || !rect.every(Number.isInteger) || rect[0] < 0 || rect[1] < 0 || rect[2] <= 0 || rect[3] <= 0) {
errors.push(`${field}: expected [x, y, width, height] with non-negative integer origins and positive integer dimensions`);
} else if (size && (rect[0] + rect[2] > size[0] || rect[1] + rect[3] > size[1])) {
errors.push(`${field}: rectangle must stay inside the image`);
}
image(`${directory}/${name}.png`);
}
return value;
}
function build(value: Record<string, unknown>, path: string) {
if (typeof value.build !== 'string' || !value.build.trim()) errors.push(`${path}.build: expected a non-empty string`);
}
const manifest = json('avatar.json', false);
if (manifest) {
try { parseManifest(manifest); }
catch (error) { errors.push((error as Error).message); }
}
const rawRig = json('rig.json');
let rig: Rig | undefined;
if (rawRig && version(rawRig, 'rig.json', false)) {
const problems = validateRig(rawRig);
errors.push(...problems.map(error => `rig.json: ${error}`));
if (!problems.length) rig = rawRig as unknown as Rig;
}
image('built/base.png'); image('built/hairmask.png');
if (rig?.cloth?.length) image('built/base_cloth.png');
const meta = json('built/layers.json');
if (meta && version(meta, 'built/layers.json')) {
build(meta, 'built/layers.json');
let size: number[] | undefined;
if (!numbers(meta.size, 2) || !meta.size.every(n => Number.isInteger(n) && n > 0)) {
errors.push('built/layers.json.size: expected [width, height] with positive integer dimensions');
} else {
size = meta.size;
if (rig && (size[0] !== rig.image.width || size[1] !== rig.image.height)) errors.push('built/layers.json.size: must match rig.json.image');
}
const rectangles = layers(meta.layers, 'built/layers.json', 'built', size);
if (rig && rectangles) {
const required = [...rig.eyes.flatMap((_, i) => ['ball', 'low', 'crease', 'lash'].map(part => `eye${i}_${part}`)),
...(rig.hand ? ['hand'] : []), ...(rig.accessories ?? []).map(part => part.name),
...(rig.cloth ?? []).map(part => `cloth_${part.name}`)];
for (const name of required) if (!own(rectangles, name)) errors.push(`built/layers.json.layers.${name}: missing required layer`);
}
if (!Array.isArray(meta.eyes) || meta.eyes.length !== 2) {
errors.push('built/layers.json.eyes: expected two eye curves');
} else meta.eyes.forEach((eye: unknown, i: number) => {
const path = `built/layers.json.eyes[${i}]`;
if (!object(eye)) { errors.push(`${path}: expected an object`); return; }
const span = numbers([eye.x0, eye.x1], 2) && (eye.x0 as number) < (eye.x1 as number);
if (!span) errors.push(`${path}: expected finite x0 < x1`);
for (const key of ['top', 'bot'] as const) {
if (!numbers(eye[key], 24)) errors.push(`${path}.${key}: expected 24 finite numbers`);
}
if (numbers(eye.top, 24) && numbers(eye.bot, 24) && eye.top.some((y, k) => y > (eye.bot as number[])[k])) {
errors.push(`${path}.top: must not exceed bottom curve`);
}
if (rig) for (const key of ['x0', 'x1', 'top', 'bot'] as const) {
const a = eye[key], b = rig.eyes[i][key];
const same = Array.isArray(b) ? numbers(a, b.length) && a.every((n, k) => n === b[k]) : a === b;
if (!same) errors.push(`${path}.${key}: must match rig.json.eyes[${i}].${key}`);
}
});
}
const sprites = json('built/sprites/sprites.json', false);
if (sprites && version(sprites, 'built/sprites/sprites.json')) {
build(sprites, 'built/sprites/sprites.json');
layers(sprites.layers, 'built/sprites/sprites.json', 'built/sprites', rig ? [rig.image.width, rig.image.height] : undefined);
}
// Optional overlay layers: { overlays: [{ name, file }] }. Unknown keys are ignored like elsewhere.
const overlays = json('built/overlays/overlays.json', false);
if (overlays && version(overlays, 'built/overlays/overlays.json')) {
if (!Array.isArray(overlays.overlays)) errors.push('built/overlays/overlays.json.overlays: expected an array');
else {
const seen = new Set<string>();
for (const [i, item] of overlays.overlays.entries()) {
const path = `built/overlays/overlays.json.overlays[${i}]`;
if (!object(item) || typeof item.name !== 'string' || !/^[A-Za-z0-9_-]+$/.test(item.name) ||
typeof item.file !== 'string' || !/^[A-Za-z0-9_-]+\.png$/.test(item.file)) {
errors.push(`${path}: expected { name, file } with safe names`); continue;
}
if (seen.has(item.name)) errors.push(`${path}.name: duplicate overlay name`);
seen.add(item.name);
image(`built/overlays/${item.file}`);
}
}
}
return errors;
}