Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

65.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  imageSource.ts — `.esimage`: a picture as a list of layers, what a model writes and edits, and what is wrong with one.
 */
import { parsePath } from './imagePath';

export const IMAGE_BLENDS = [
    'normal', 'multiply', 'screen', 'overlay', 'add', 'softLight', 'hardLight', 'vividLight', 'linearLight', 'pinLight', 'colorDodge', 'colorBurn', 'linearBurn',
    'darken', 'lighten', 'difference', 'exclusion', 'subtract', 'divide', 'hue', 'saturation', 'color', 'luminosity',
] as const;
export type ImageBlend = (typeof IMAGE_BLENDS)[number];

/** Adjustments of the picture so far. Any of them together, applied in this order. */
export interface ImageAdjust {
    /** Stops, as a photo's: 1 is twice as bright. */
    exposure?: number;
    levels?: { input?: readonly [number, number]; gamma?: number; output?: readonly [number, number] };
    /** [[in, out]...] 0..1 for all channels, or { r, g, b } for each. */
    curves?: readonly (readonly number[])[] | { r?: readonly (readonly number[])[]; g?: readonly (readonly number[])[]; b?: readonly (readonly number[])[] };
    brightness?: number;
    contrast?: number;
    temperature?: number;
    tint?: number;
    /** Each [r, g, b], -1..1, pushing that part of the tonal range. */
    balance?: { shadows?: readonly number[]; midtones?: readonly number[]; highlights?: readonly number[] };
    /** Degrees round the wheel, and -1..1 each. */
    hue?: number;
    saturation?: number;
    lightness?: number;
    vibrance?: number;
    /** true, or how much of [r, g, b] each makes the grey. */
    blackWhite?: boolean | readonly number[];
    gradientMap?: readonly (readonly [number, string])[];
    invert?: boolean;
    posterize?: number;
    threshold?: number;
}

const ADJUST_RANGES: Readonly<Record<string, readonly [number, number]>> = { exposure: [-8, 8], brightness: [-1, 1], contrast: [-1, 1], temperature: [-1, 1], tint: [-1, 1], hue: [-360, 360], saturation: [-1, 1], lightness: [-1, 1], vibrance: [-1, 1], posterize: [2, 256], threshold: [0, 1] };

function adjustProblem(a: unknown): string | null {
    if (typeof a !== 'object' || a === null) return 'must be an object of what to change';
    const o = a as Record<string, unknown>;
    const known = [...Object.keys(ADJUST_RANGES), 'levels', 'curves', 'balance', 'blackWhite', 'gradientMap', 'invert'];
    for (const key of Object.keys(o)) if (!known.includes(key)) return `has unknown "${key}"; there are ${known.join(', ')}`;
    if (Object.keys(o).length === 0) return 'changes nothing';
    for (const [key, [lo, hi]] of Object.entries(ADJUST_RANGES)) if (o[key] !== undefined && !(isNum(o[key]) && (o[key] as number) >= lo && (o[key] as number) <= hi)) return `${key} must be ${lo}..${hi}`;
    const unitPair = (v: unknown): boolean => isPair(v) && (v as number[]).every((n) => n >= 0 && n <= 1);
    const curve = (v: unknown): boolean => Array.isArray(v) && v.length >= 2 && v.every(unitPair);
    if (o.levels !== undefined) {
        const l = o.levels as Record<string, unknown>;
        if (typeof l !== 'object' || l === null) return 'levels must be { input?, gamma?, output? }';
        for (const key of Object.keys(l)) if (!['input', 'gamma', 'output'].includes(key)) return `levels has unknown "${key}"; there are input, gamma, output`;
        for (const key of ['input', 'output']) if (l[key] !== undefined && !unitPair(l[key])) return `levels ${key} must be [low, high], each 0..1`;
        if (l.gamma !== undefined && !(isNum(l.gamma) && (l.gamma as number) > 0)) return 'levels gamma must be positive';
    }
    if (o.curves !== undefined) {
        if (Array.isArray(o.curves)) { if (!curve(o.curves)) return 'curves must be two or more [in, out], each 0..1'; }
        else {
            const c = o.curves as Record<string, unknown>;
            if (typeof c !== 'object' || c === null) return 'curves must be [[in, out]...] or { r, g, b }';
            for (const [key, v] of Object.entries(c)) { if (!['r', 'g', 'b'].includes(key)) return `curves has unknown "${key}"; there are r, g, b`; if (!curve(v)) return `curves ${key} must be two or more [in, out], each 0..1`; }
        }
    }
    if (o.balance !== undefined) {
        for (const [key, v] of Object.entries(o.balance as Record<string, unknown>)) {
            if (!['shadows', 'midtones', 'highlights'].includes(key)) return `balance has unknown "${key}"; there are shadows, midtones, highlights`;
            if (!(Array.isArray(v) && v.length === 3 && v.every(isNum))) return `balance ${key} must be [r, g, b]`;
        }
    }
    if (o.blackWhite !== undefined && typeof o.blackWhite !== 'boolean' && !(Array.isArray(o.blackWhite) && o.blackWhite.length === 3 && o.blackWhite.every(isNum))) return 'blackWhite must be true or [r, g, b]';
    if (o.invert !== undefined && typeof o.invert !== 'boolean') return 'invert must be true or false';
    if (o.gradientMap !== undefined && !(Array.isArray(o.gradientMap) && o.gradientMap.length >= 2 && o.gradientMap.every((s) => Array.isArray(s) && s.length === 2 && isNum(s[0]) && isColor(s[1])))) return 'gradientMap must be two or more [0..1, colour]';
    return null;
}

/** Every filter and what it takes. A number but for: `at`, `from`, `to` a place; `color` a colour; `mono` true or false. */
export const IMAGE_FILTERS = {
    gaussian: ['radius'], motion: ['angle', 'distance'], spin: ['at', 'angle'], zoom: ['at', 'amount'], lens: ['radius', 'highlights'],
    sharpen: ['amount', 'radius', 'threshold'], highPass: ['radius'], noise: ['amount', 'scale', 'mono', 'seed'], median: ['radius'], emboss: ['angle', 'height', 'amount'],
    ripple: ['amount', 'size', 'seed'], displace: ['amount', 'size', 'seed'], twirl: ['at', 'radius', 'angle'], pixelate: ['cell'], chromatic: ['at', 'amount'],
    vignette: ['at', 'amount', 'radius', 'outer', 'color'], fog: ['color', 'density', 'from', 'to', 'patchiness', 'size', 'seed'], rays: ['at', 'threshold', 'length', 'strength', 'decay'],
    flare: ['at', 'size', 'color', 'strength'], texture: ['scale', 'amount', 'angle', 'seed'],
} as const;
export type ImageFilterName = keyof typeof IMAGE_FILTERS;

function filterProblem(name: unknown, params: unknown): string | null {
    if (typeof name !== 'string' || !Object.prototype.hasOwnProperty.call(IMAGE_FILTERS, name)) return `filter ${JSON.stringify(name)} must be one of ${Object.keys(IMAGE_FILTERS).join(', ')}`;
    if (params === undefined) return null;
    if (typeof params !== 'object' || params === null) return 'params must be an object';
    const known = IMAGE_FILTERS[name as ImageFilterName] as readonly string[];
    for (const [key, v] of Object.entries(params)) {
        if (!known.includes(key)) return `filter ${name} has unknown "${key}"; it takes ${known.join(', ')}`;
        if (key === 'color') { if (!isColor(v)) return `filter ${name}: color must be #rgb..#rrggbbaa`; }
        else if (key === 'at' || key === 'from' || key === 'to') { if (!isPair(v)) return `filter ${name}: ${key} must be [x, y]`; }
        else if (key === 'mono') { if (typeof v !== 'boolean') return `filter ${name}: mono must be true or false`; }
        else if (!isNum(v)) return `filter ${name}: ${key} must be a number`;
    }
    return null;
}

export const IMAGE_SOURCE_EXT = '.esimage';
export const IMAGE_SOURCE_VERSION = 1;
export const MAX_IMAGE_SIZE = 2048;

export type ImageFill = string
    | { type: 'linear'; from: readonly [number, number]; to: readonly [number, number]; stops: readonly (readonly [number, string])[] }
    | { type: 'radial'; at: readonly [number, number]; radius: number; stops: readonly (readonly [number, string])[] }
    /** The same picture on every machine: it comes from `seed` and never from a random number. */
    | { type: 'noise'; scale?: number; octaves?: number; seed?: number; stops: readonly (readonly [number, string])[] }
    /** By which way a figure's surface faces: 1 toward the light, 0.5 side on, 0 away. So light turns the form and does not sit on its edge. */
    | { type: 'form'; figure: string; light?: readonly number[]; stops: readonly (readonly [number, string])[] }
    /** The colour of an `image` layer at each place. */
    | { type: 'image'; image: string }
    /** Marks in rows and columns: windows, tiles, grilles. On four corners it lies in perspective. */
    | {
        type: 'grid';
        /** A cell's size in pixels, or with `quad` how many columns and rows there are. */
        cell?: readonly [number, number];
        cells?: readonly [number, number];
        /** Corners in order round: top left, top right, bottom right, bottom left. */
        quad?: readonly (readonly number[])[];
        /** The mark as a share of its cell, each 0..1. */
        mark?: readonly [number, number];
        colors: readonly string[];
        /** Between the marks; clear without it. */
        ground?: string;
        /** The share of marks that are on, 0..1, and what the rest show. */
        lit?: number;
        off?: string;
        seed?: number;
    };

export interface ImageEffect {
    type: 'shadow' | 'glow' | 'innerShadow' | 'innerGlow' | 'bevel' | 'overlay';
    /** A bevel: how wide, the light's direction in degrees, how strong, and the colour on its dark side. */
    size?: number;
    angle?: number;
    depth?: number;
    shade?: string;
    /** An overlay: what covers the shape. */
    fill?: ImageFill;
    blend?: ImageBlend;
    color?: string;
    x?: number;
    y?: number;
    blur?: number;
    opacity?: number;
}

export interface ImageTransform {
    translate?: readonly [number, number];
    /** Degrees, clockwise on screen, about `origin`. */
    rotate?: number;
    scale?: number | readonly [number, number];
    /** Default the layer's middle. */
    origin?: readonly [number, number];
}

export type ImageShape = 'rect' | 'circle' | 'ellipse' | 'ring' | 'polygon' | 'line' | 'star' | 'gear' | 'path' | 'pixels' | 'paint' | 'figure' | 'image' | 'text' | 'block' | 'perspective' | 'reflect' | 'bloom' | 'adjust' | 'filter' | 'group';

/** How a brush lays colour. Any of these on a stroke, a sweep or a field, over what its `brush` starts from. */
export interface ImageBrushSettings {
    hardness?: number;
    opacity?: number;
    taper?: readonly [number, number];
    /** 1 round; lower is a flat brush, thin along its travel and wide across it. */
    roundness?: number;
    /** Degrees the flat of the brush is held at, which gives thick and thin as a pen does. Without it the brush turns with the stroke. */
    angle?: number;
    /** 0..1: how much the tooth of the paper breaks it up, in a texture fixed to the picture. */
    grain?: number;
    grainScale?: number;
    /** 0..1: how much the brush runs dry, in streaks along its travel. */
    dry?: number;
    /** 0..1: how much it picks up what is under it as it goes. */
    wet?: number;
    /** 0..1: pigment gathered at the edge, as watercolour dries. */
    edge?: number;
    /** Each dab this many brush radii off the line. */
    scatter?: number;
    /** The dabs as a share of the brush's size: small, and scattered, they are a spray. */
    dab?: number;
    /** Between dabs, as a share of a dab's width. */
    spacing?: number;
    /** 0..1: each dab adds this much, so paint builds where it passes, as an airbrush does, and opacity no longer caps it. */
    flow?: number;
    /** How much of the length at each end fades out, each 0..1. */
    fade?: readonly [number, number];
}

/** Named starting points, in the words a painter uses. */
export const IMAGE_BRUSHES: Readonly<Record<string, ImageBrushSettings>> = {
    ink: { hardness: 1, taper: [0.12, 0.3] },
    pen: { hardness: 1, roundness: 0.25, angle: -45 },
    pencil: { hardness: 0.6, grain: 0.35, grainScale: 1.2, opacity: 0.75 },
    charcoal: { hardness: 0.35, grain: 0.5, grainScale: 2.2, dry: 0.12, opacity: 0.95 },
    chalk: { hardness: 0.7, grain: 0.55, grainScale: 6, opacity: 0.95 },
    flat: { hardness: 0.85, roundness: 0.3, dry: 0.3 },
    oil: { hardness: 0.65, roundness: 0.55, dry: 0.22, wet: 0.55, opacity: 0.95 },
    gouache: { hardness: 0.8, roundness: 0.5, wet: 0.2, dry: 0.08, opacity: 0.95 },
    watercolor: { hardness: 0.2, wet: 0.45, edge: 0.5, opacity: 0.45, grain: 0.05, grainScale: 5 },
    marker: { hardness: 0.9, roundness: 0.45, angle: -30, opacity: 0.72 },
    airbrush: { hardness: 0, flow: 0.05 },
    spray: { hardness: 0.7, dab: 0.07, scatter: 1, spacing: 0.5, opacity: 0.9 },
    dry: { hardness: 0.75, roundness: 0.35, dry: 0.65, opacity: 0.95 },
};
const BRUSH_FIELDS = ['brush', 'roundness', 'angle', 'grain', 'grainScale', 'dry', 'wet', 'edge', 'scatter', 'dab', 'spacing', 'flow', 'fade'];

/** One movement of a brush. Replayed in order on a `paint` layer, so the same list is the same picture. */
export interface ImageStroke extends ImageBrushSettings {
    /** A named brush from IMAGE_BRUSHES, which what else is given here overrides. */
    brush?: string;
    /** Through these, smoothly; a third number is pressure, 1 by default. One point is a dab. */
    points: readonly (readonly number[])[];
    color?: string;
    /** The colour it has become by the end. */
    to?: string;
    size: number;
    /** 1 is a hard edge, 0 fades from the middle. */
    hardness?: number;
    opacity?: number;
    /** How much of the length at each end narrows to a point, each 0..1. */
    taper?: readonly [number, number];
    /** Separate hairs across its width, which meet where it narrows. */
    bristles?: number;
    /** The width of a bristle; by default what spreads them across the stroke. */
    strand?: number;
    spread?: number;
    /** How far each bristle's lightness and strength differ, 0..1. */
    vary?: number;
    /** How far a bristle wanders from its line, in pixels. */
    wobble?: number;
    seed?: number;
    /** 0..1: drags what is already on this layer along, instead of laying colour. */
    smudge?: number;
    erase?: boolean;
    blend?: ImageBlend;
}

/** Many hairs between guide lines, gathered into locks. A few words of intent, and hundreds of strokes when drawn. */
export interface ImageSweep extends ImageBrushSettings {
    type: 'sweep';
    brush?: string;
    /** Two or more lines, side by side and in order, each root to tip. */
    guides: readonly (readonly (readonly number[])[])[];
    /** Across the guides, first to last. */
    colors: readonly string[];
    count: number;
    /** What the colours have turned to by the tips. */
    tip?: string;
    /** The width of one hair. */
    size?: number;
    clumps?: number;
    /** How far hairs draw into their lock by the tips, 0..1. */
    gather?: number;
    /** The share of hairs that stray from the mass, 0..1. */
    flyaway?: number;
    vary?: number;
    wobble?: number;
    opacity?: number;
    taper?: readonly [number, number];
    seed?: number;
}

/** A region covered in strokes that follow a flow, each its colour from `tone` where it starts. */
export interface ImageField extends ImageBrushSettings {
    type: 'field';
    brush?: string;
    /** An SVG path to start strokes in, or "@id" for where an earlier layer drew; the whole picture without it. Strokes may run over its edge. */
    region?: string;
    /** Lines the strokes follow, nearest the most, or a direction in degrees clockwise from right. */
    guides?: readonly (readonly (readonly number[])[])[];
    angle?: number;
    /** Where each stroke takes its colour; left out when it smudges. */
    tone?: ImageFill;
    /** 0..1: the strokes drag what is there along the flow, and lay no colour. */
    smudge?: number;
    size: number;
    length?: number;
    /** How many times over the strokes cover the region. */
    coverage?: number;
    /** Degrees either side of the flow. */
    spread?: number;
    vary?: number;
    opacity?: number;
    hardness?: number;
    seed?: number;
}

/** The same strokes again and again along a line: feathers, scales, leaves, beads. */
export interface ImageAlong {
    type: 'along';
    line: readonly (readonly number[])[];
    count: number;
    /** Drawn with x along the line and y across it, about the point [0, 0]. */
    strokes: readonly ImageStroke[];
    /** How large they are at the start of the line and at the end. */
    scale?: number | readonly [number, number];
    /** Degrees, added to the line's direction. */
    turn?: number;
    /** Each one again, reflected across the line. */
    both?: boolean;
    /** Up to this far off their place, in pixels and a tenth as many degrees. */
    jitter?: number;
    seed?: number;
}

export type ImageMark = ImageStroke | ImageSweep | ImageField | ImageAlong;

export interface ImageLayer {
    id?: string;
    shape: ImageShape;
    at?: readonly [number, number];
    size?: readonly [number, number];
    radius?: number | readonly number[];
    radii?: readonly [number, number];
    inner?: number;
    count?: number;
    tooth?: number;
    turn?: number;
    points?: readonly (readonly [number, number])[];
    d?: string;
    rows?: readonly string[];
    palette?: Readonly<Record<string, string>>;
    scale?: number;
    layers?: readonly ImageLayer[];
    strokes?: readonly ImageMark[];
    /** "below": a paint layer's canvas starts as the picture so far, so its strokes and smudges work across everything under it. */
    from?: 'below';
    /** Seen when looking and left out of the .png, while what it masks still works. A figure is one unless told otherwise. */
    guide?: boolean;
    /** A figure: pixels from floor to crown, standing straight. */
    height?: number;
    /** A figure: degrees turned about the body, 0 facing the viewer, 90 facing picture right, 180 away. */
    yaw?: number;
    /** A figure: degrees seen from above. */
    pitch?: number;
    build?: { head?: number; shoulders?: number; chest?: number; waist?: number; hips?: number; limbs?: number };
    pose?: {
        rotate?: Readonly<Record<string, readonly number[]>>;
        move?: Readonly<Record<string, readonly number[]>>;
        /** A joint and where it must be: [x, y] in the picture, or [x, y, z] on the body's own axes. */
        reach?: Readonly<Record<string, { at: readonly number[]; pole?: readonly number[] }>>;
    };
    /** Text: what it says. */
    text?: string;
    fontSize?: number;
    /** A family the machine has, or a font file in the project. */
    font?: string;
    weight?: number | string;
    align?: 'left' | 'center' | 'right';
    /** Characters one under the other, as a sign down a building. */
    vertical?: boolean;
    /** Extra between characters, in pixels. */
    tracking?: number;
    /** Text: pixels taken off each stroke of the letters, for the white-hot core of a neon tube. */
    thin?: number;
    /** Text: 0..1 how much the surface shows through, as worn paint, and how much it is rubbed away in streaks. */
    grain?: number;
    grainScale?: number;
    dry?: number;
    /** Text or paint: a face of a block already drawn, "id.a", to lie on: text within `within`, and strokes with their points counted 0..1 across it and 0..1 down. */
    face?: string;
    /** On a face, the part it takes: left, top, right, bottom, each 0..1. */
    within?: readonly number[];
    /** Text: four corners in the picture it is laid on, in order round from the top left, so it lies on a wall in perspective. */
    quad?: readonly (readonly number[])[];
    /** Pixels of soft edge on the layer, fading inward, keeping its colour where a blur would smear it. */
    feather?: number;
    /** What it clips to, softened, grown or shrunk, or turned inside out. */
    clipFeather?: number;
    clipGrow?: number;
    clipInvert?: boolean;
    /** Only where the picture so far is this light, [low, high, softness?] each 0..1: a highlight or shadow selected by what it is. */
    blendIf?: readonly number[];
    adjust?: ImageAdjust;
    filter?: ImageFilterName;
    params?: Readonly<Record<string, unknown>>;
    /** A bloom: how bright a pixel must be to shine, 0..1, and how much it does. */
    threshold?: number;
    strength?: number;
    /** A block or a perspective: the points lines recede to. */
    vanish?: readonly (readonly number[])[];
    /** A block: how far each face runs toward its vanishing point, 0..1. */
    depth?: readonly number[];
    /** A block: the fill of each face, and of the roof if it can be seen. */
    faces?: readonly ImageFill[];
    roof?: ImageFill;
    /** A reflect: the line it mirrors about, level or as points along where things meet the ground, how far down it reaches, and how far it wavers and smears in pixels. */
    y?: number;
    edge?: readonly (readonly number[])[];
    reach?: number;
    ripple?: number;
    smear?: number;
    /** An image: a picture in the project. */
    src?: string;
    /** Drawn everywhere but inside this earlier layer. */
    except?: string;
    /** A figure: where the light is, x right, y up, z toward the viewer. */
    light?: readonly number[];
    fill?: ImageFill;
    stroke?: { color: ImageFill; width: number; align?: 'center' | 'inside' | 'outside'; join?: 'round' | 'miter' | 'bevel'; cap?: 'round' | 'butt' | 'square' };
    opacity?: number;
    blend?: ImageBlend;
    transform?: ImageTransform;
    mirror?: 'x' | 'y';
    effects?: readonly ImageEffect[];
    clip?: string;
    erase?: boolean;
    visible?: boolean;
    /** Softens the layer as drawn, with its effects, in the picture's pixels. On a group it softens the group as one thing. */
    blur?: number;
}

export interface ImageSource {
    version?: number;
    size: number | readonly [number, number];
    background?: string;
    /**
     * The picture repeats: laid edge to edge with itself it shows no seam. What is drawn past one edge comes in at the
     * opposite one, a blur or a shadow goes round with it, and a noise fill repeats with the picture. For a wall, a floor,
     * a cloth: anything a surface is covered with.
     */
    tile?: boolean;
    /** What the surface is, beside what it looks like: see {@link ImageMaterial}. With it, a normal map and a material are written beside the picture. */
    material?: ImageMaterial;
    layers: readonly ImageLayer[];
}

/**
 * A picture as a surface. Each part is a number for the whole of it, or layers drawn as a grey picture of their own:
 * light is high, light is rough, light is metal.
 */
export interface ImageMaterial {
    /** How far white stands above black, in pixels of the picture. Default 4. */
    relief?: number;
    /** The relief, drawn: light is high. Default: the colour picture's own lightness, dark being low. */
    height?: readonly ImageLayer[];
    /** How rough, 0..1 everywhere, or drawn: light is rough. Default 0.8. */
    roughness?: number | readonly ImageLayer[];
    /** How much metal, 0..1 everywhere, or drawn: light is metal. Default 0. */
    metal?: number | readonly ImageLayer[];
}

const isNum = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
const isPair = (v: unknown): boolean => Array.isArray(v) && v.length === 2 && v.every(isNum);
const isColor = (v: unknown): boolean => typeof v === 'string' && /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(v);

function checkFill(v: unknown): string | null {
    if (typeof v === 'string') return isColor(v) ? null : `${JSON.stringify(v)} must be #rgb, #rgba, #rrggbb or #rrggbbaa`;
    const f = v as Record<string, unknown> | null;
    if (typeof f !== 'object' || f === null) return 'must be a colour or a gradient';
    if (f.type !== 'linear' && f.type !== 'radial' && f.type !== 'noise' && f.type !== 'form' && f.type !== 'image' && f.type !== 'grid') return 'a gradient has type linear, radial, noise, form, image or grid';
    if (f.type === 'grid') {
        if (!Array.isArray(f.colors) || f.colors.length === 0 || !f.colors.every(isColor)) return 'a grid needs colors: one or more';
        for (const key of ['ground', 'off']) if (f[key] !== undefined && !isColor(f[key])) return `a grid's ${key} must be a colour`;
        const quad = f.quad as unknown[] | undefined;
        if (quad !== undefined && !(Array.isArray(quad) && quad.length === 4 && quad.every(isPair))) return 'a grid\'s quad must be four [x, y], in order round from the top left';
        if (f.cell === undefined && f.cells === undefined) return 'a grid needs cell: [w, h] in pixels, or cells: [columns, rows]';
        for (const key of ['cell', 'cells']) if (f[key] !== undefined && !(isPair(f[key]) && (f[key] as number[]).every((v) => v > 0))) return `a grid's ${key} must be two positive numbers`;
        if (f.cell !== undefined && quad !== undefined) return 'a grid on a quad is counted in cells: [columns, rows]';
        if (f.mark !== undefined && !(isPair(f.mark) && (f.mark as number[]).every((v) => v > 0 && v <= 1))) return 'a grid\'s mark must be [w, h], each above 0 and up to 1';
        if (f.lit !== undefined && !(isNum(f.lit) && (f.lit as number) >= 0 && (f.lit as number) <= 1)) return 'a grid\'s lit must be 0..1';
        if (f.seed !== undefined && !Number.isInteger(f.seed)) return 'a grid\'s seed must be a whole number';
        return null;
    }
    if (f.type === 'image') return typeof f.image === 'string' && f.image ? null : 'an image fill needs image, the id of an image layer drawn before it';
    if (f.type === 'form') {
        if (typeof f.figure !== 'string' || !f.figure) return 'a form needs figure, the id of a figure drawn before it';
        if (f.light !== undefined && !(Array.isArray(f.light) && f.light.length === 3 && f.light.every(isNum))) return 'a form\'s light must be [x, y, z], x right, y up, z toward the viewer';
    }
    if (f.type === 'noise') {
        if (f.scale !== undefined && !(isNum(f.scale) && (f.scale as number) > 0)) return 'noise scale must be a positive number of pixels';
        if (f.octaves !== undefined && !(Number.isInteger(f.octaves) && (f.octaves as number) >= 1 && (f.octaves as number) <= 8)) return 'noise octaves must be a whole number from 1 to 8';
        if (f.seed !== undefined && !Number.isInteger(f.seed)) return 'noise seed must be a whole number';
    }
    if (f.type === 'linear' && !(isPair(f.from) && isPair(f.to))) return 'a linear gradient needs from and to, each [x, y]';
    if (f.type === 'linear' && (f.from as number[])[0] === (f.to as number[])[0] && (f.from as number[])[1] === (f.to as number[])[1]) return 'a linear gradient needs from and to apart: at one point it draws a single flat colour';
    if (f.type === 'radial' && !(isPair(f.at) && isNum(f.radius) && (f.radius as number) > 0)) return 'a radial gradient needs at: [x, y] and a positive radius';
    if (!Array.isArray(f.stops) || f.stops.length < 2) return 'a gradient needs two stops or more, each [0..1, colour]';
    for (const s of f.stops as unknown[]) {
        if (!Array.isArray(s) || s.length !== 2 || !isNum(s[0]) || !isColor(s[1])) return `a stop ${JSON.stringify(s)} must be [0..1, colour]`;
    }
    return null;
}

const FIELDS = ['id', 'shape', 'at', 'size', 'radius', 'radii', 'inner', 'count', 'tooth', 'turn', 'points', 'd', 'rows', 'palette', 'scale', 'layers', 'fill', 'stroke', 'opacity', 'blend', 'transform', 'mirror', 'effects', 'clip', 'erase', 'visible', 'blur', 'strokes', 'from', 'guide', 'height', 'yaw', 'pitch', 'build', 'pose', 'light', 'src', 'except', 'text', 'fontSize', 'font', 'weight', 'align', 'vertical', 'tracking', 'vanish', 'depth', 'faces', 'roof', 'y', 'edge', 'reach', 'ripple', 'smear', 'quad', 'threshold', 'strength', 'thin', 'grain', 'grainScale', 'dry', 'face', 'within', 'feather', 'clipFeather', 'clipGrow', 'clipInvert', 'blendIf', 'adjust', 'filter', 'params'];

/** Layers that are aids to drawing unless told otherwise: seen when looking, and not in the .png. */
export const isGuideLayer = (l: ImageLayer): boolean => l.guide ?? (l.shape === 'figure' || l.shape === 'image' || l.shape === 'perspective');
const SHAPES: readonly ImageShape[] = ['rect', 'circle', 'ellipse', 'ring', 'polygon', 'line', 'star', 'gear', 'path', 'pixels', 'paint', 'figure', 'image', 'text', 'block', 'perspective', 'reflect', 'bloom', 'adjust', 'filter', 'group'];
const STROKE_FIELDS = ['points', 'color', 'to', 'size', 'hardness', 'opacity', 'taper', 'bristles', 'strand', 'spread', 'vary', 'wobble', 'seed', 'smudge', 'erase', 'blend', ...BRUSH_FIELDS];

/** What a brush's own settings must be, on whatever carries them. */
function brushProblem(s: Record<string, unknown>): string | null {
    if (s.brush !== undefined && !(typeof s.brush === 'string' && Object.prototype.hasOwnProperty.call(IMAGE_BRUSHES, s.brush))) return `brush ${JSON.stringify(s.brush)} must be one of ${Object.keys(IMAGE_BRUSHES).join(', ')}`;
    for (const key of ['roundness', 'grain', 'dry', 'wet', 'edge', 'dab', 'flow']) {
        if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
    }
    if (s.roundness === 0 || s.dab === 0) return `${s.roundness === 0 ? 'roundness' : 'dab'} must be above 0`;
    for (const key of ['grainScale', 'spacing']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) > 0)) return `${key} must be positive`;
    if (s.scatter !== undefined && !(isNum(s.scatter) && (s.scatter as number) >= 0)) return 'scatter must be 0 or more';
    if (s.angle !== undefined && !isNum(s.angle)) return 'angle must be degrees';
    if (s.fade !== undefined && !(Array.isArray(s.fade) && s.fade.length === 2 && s.fade.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'fade must be [start, end], each 0..1';
    return null;
}

const SWEEP_FIELDS = ['type', 'guides', 'colors', 'count', 'tip', 'size', 'clumps', 'gather', 'flyaway', 'vary', 'wobble', 'opacity', 'taper', 'seed', 'hardness', ...BRUSH_FIELDS];
const ALONG_FIELDS = ['type', 'line', 'count', 'strokes', 'scale', 'turn', 'both', 'jitter', 'seed'];
const FIELD_FIELDS = ['type', 'region', 'guides', 'angle', 'tone', 'smudge', 'size', 'length', 'coverage', 'spread', 'vary', 'opacity', 'hardness', 'seed', 'taper', ...BRUSH_FIELDS];
const isGuide = (g: unknown): boolean => Array.isArray(g) && g.length >= 2 && g.every((p) => Array.isArray(p) && (p.length === 2 || p.length === 3) && p.every(isNum));
export const MAX_MARK_STROKES = 30000;

function markProblem(s: Record<string, unknown>): string | null {
    const zeroToOne = (keys: readonly string[]): string | null => {
        for (const key of keys) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
        return null;
    };
    const fields = s.type === 'sweep' ? SWEEP_FIELDS : s.type === 'along' ? ALONG_FIELDS : FIELD_FIELDS;
    for (const key of Object.keys(s)) if (!fields.includes(key)) return `has unknown field "${key}"; a ${String(s.type)} takes ${fields.join(', ')}`;
    if (s.seed !== undefined && !Number.isInteger(s.seed)) return 'seed must be a whole number';
    if (s.type !== 'along') {
        const bad = brushProblem(s);
        if (bad) return bad;
    }
    if (s.type === 'sweep') {
        if (!Array.isArray(s.guides) || s.guides.length < 2 || !s.guides.every(isGuide)) return 'needs guides: two or more lines, each two or more [x, y]';
        if (!Array.isArray(s.colors) || s.colors.length === 0 || !s.colors.every(isColor)) return 'needs colors: one or more, across the guides';
        if (s.tip !== undefined && !isColor(s.tip)) return 'tip must be a colour';
        if (!(Number.isInteger(s.count) && (s.count as number) >= 1 && (s.count as number) <= MAX_MARK_STROKES)) return `count must be a whole number from 1 to ${MAX_MARK_STROKES}`;
        if (s.clumps !== undefined && !(Number.isInteger(s.clumps) && (s.clumps as number) >= 1)) return 'clumps must be a whole number of 1 or more';
        for (const key of ['size', 'wobble']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0)) return `${key} must be 0 or more`;
        if (s.taper !== undefined && !(Array.isArray(s.taper) && s.taper.length === 2 && s.taper.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'taper must be [start, end], each 0..1';
        return zeroToOne(['gather', 'flyaway', 'vary', 'opacity']);
    }
    if (s.type === 'along') {
        if (!isGuide(s.line)) return 'needs a line: two or more [x, y]';
        if (!(Number.isInteger(s.count) && (s.count as number) >= 1 && (s.count as number) <= 2000)) return 'count must be a whole number from 1 to 2000';
        if (!Array.isArray(s.strokes) || s.strokes.length === 0) return 'needs strokes, drawn about [0, 0]';
        for (const [n, inner] of (s.strokes as Record<string, unknown>[]).entries()) {
            if (inner?.type !== undefined) return `strokes[${n}] must be a plain stroke`;
            const bad = strokeProblem(inner);
            if (bad) return `strokes[${n}] ${bad}`;
        }
        const scale = s.scale;
        if (scale !== undefined && !(isNum(scale) && scale > 0) && !(isPair(scale) && (scale as number[]).every((v) => v > 0))) return 'scale must be a positive number, or [start, end]';
        for (const key of ['turn', 'jitter']) if (s[key] !== undefined && !isNum(s[key])) return `${key} must be a number`;
        return null;
    }
    if (s.region !== undefined) {
        if (typeof s.region !== 'string') return 'region must be an SVG path or "@id"';
        if (!s.region.startsWith('@')) {
            try { parsePath(s.region); } catch (e) { return `region: ${(e as Error).message}`; }
        }
    }
    if (s.guides !== undefined && !(Array.isArray(s.guides) && s.guides.length > 0 && s.guides.every(isGuide))) return 'guides must be one or more lines, each two or more [x, y]';
    if (s.angle !== undefined && !isNum(s.angle)) return 'angle must be degrees';
    if (s.tone === undefined && !s.smudge) return 'needs a tone, unless it smudges';
    if (s.tone !== undefined) {
        const bad = checkFill(s.tone);
        if (bad) return `tone ${bad}`;
    }
    for (const key of ['size', 'length', 'coverage']) {
        if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) > 0)) return `${key} must be positive`;
    }
    if (s.size === undefined) return 'needs a positive size';
    if (s.spread !== undefined && !(isNum(s.spread) && (s.spread as number) >= 0)) return 'spread must be 0 or more degrees';
    return zeroToOne(['vary', 'opacity', 'hardness', 'smudge']);
}

function strokeProblem(s: Record<string, unknown>): string | null {
    if (typeof s !== 'object' || s === null) return 'must be an object';
    if (s.type === undefined) {
        const bad = brushProblem(s);
        if (bad) return bad;
    }
    if (s.type === 'sweep' || s.type === 'field' || s.type === 'along') return markProblem(s);
    if (s.type !== undefined) return `has type "${String(s.type)}"; there are sweep, field and along, or none for one stroke`;
    for (const key of Object.keys(s)) if (!STROKE_FIELDS.includes(key)) return `has unknown field "${key}"; a stroke takes ${STROKE_FIELDS.join(', ')}`;
    if (!Array.isArray(s.points) || s.points.length === 0 || !s.points.every((p) => Array.isArray(p) && (p.length === 2 || p.length === 3) && p.every(isNum))) return 'needs points, each [x, y] or [x, y, pressure]';
    if (!(isNum(s.size) && (s.size as number) > 0)) return 'needs a positive size';
    const paints = !s.erase && !s.smudge;
    if (paints && s.color === undefined) return 'needs a color, unless it erases or smudges';
    for (const key of ['color', 'to']) if (s[key] !== undefined && !isColor(s[key])) return `${key} must be #rgb, #rgba, #rrggbb or #rrggbbaa`;
    for (const key of ['hardness', 'opacity', 'vary', 'smudge']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0 && (s[key] as number) <= 1)) return `${key} must be 0..1`;
    for (const key of ['strand', 'spread', 'wobble']) if (s[key] !== undefined && !(isNum(s[key]) && (s[key] as number) >= 0)) return `${key} must be 0 or more`;
    if (s.bristles !== undefined && !(Number.isInteger(s.bristles) && (s.bristles as number) >= 1 && (s.bristles as number) <= 200)) return 'bristles must be a whole number from 1 to 200';
    if (s.seed !== undefined && !Number.isInteger(s.seed)) return 'seed must be a whole number';
    if (s.taper !== undefined && !(Array.isArray(s.taper) && s.taper.length === 2 && s.taper.every((t) => isNum(t) && t >= 0 && t <= 1))) return 'taper must be [start, end], each 0..1';
    if (s.blend !== undefined && !IMAGE_BLENDS.includes(s.blend as ImageBlend)) return `blend must be one of ${IMAGE_BLENDS.join(', ')}`;
    return null;
}

function checkLayer(l: Record<string, unknown>, where: string, ids: Set<string>): void {
    const fail = (what: string): never => { throw new Error(`${where}: ${what}`); };
    if (typeof l !== 'object' || l === null) fail('must be an object');
    for (const key of Object.keys(l)) if (!FIELDS.includes(key)) fail(`unknown field "${key}"; a layer takes ${FIELDS.join(', ')}`);
    if (!SHAPES.includes(l.shape as ImageShape)) fail(`shape ${JSON.stringify(l.shape)} must be one of ${SHAPES.join(', ')}`);
    if (l.id !== undefined) {
        if (typeof l.id !== 'string' || !l.id) fail('id must be a string');
        if (ids.has(l.id as string)) fail(`the id "${String(l.id)}" is already used`);
        ids.add(l.id as string);
    }
    const num = (k: string, ok: (n: number) => boolean = () => true): void => { if (!isNum(l[k]) || !ok(l[k] as number)) fail(`${k} must be a number${ok === positive ? ' above 0' : ''}`); };
    const pair = (k: string): void => { if (!isPair(l[k])) fail(`${k} must be [a, b]`); };
    const positive = (n: number): boolean => n > 0;
    switch (l.shape) {
        case 'rect': if (l.face === undefined) { pair('at'); pair('size'); } if (l.radius !== undefined && !isNum(l.radius) && !(Array.isArray(l.radius) && l.radius.length === 4 && l.radius.every(isNum))) fail('radius must be a number or four corners'); break;
        case 'circle': pair('at'); num('radius', positive); break;
        case 'ellipse': pair('at'); pair('radii'); break;
        case 'ring': pair('at'); num('radius', positive); num('inner', positive); if ((l.inner as number) >= (l.radius as number)) fail('inner must be less than radius'); break;
        case 'polygon': case 'line':
            if (!Array.isArray(l.points) || l.points.length < (l.shape === 'line' ? 2 : 3) || !l.points.every(isPair)) fail(`points must be ${l.shape === 'line' ? 'two' : 'three'} or more [x, y]`);
            if (l.shape === 'line' && !l.stroke) fail('a line needs a stroke: { color, width }');
            break;
        case 'star': case 'gear': pair('at'); num('radius', positive); num('inner', positive); if (!Number.isInteger(l.count) || (l.count as number) < 3) fail('count must be 3 or more'); break;
        case 'path':
            if (typeof l.d !== 'string' || !l.d.trim()) fail('d must be an SVG path: M L H V C S Q T Z');
            // Here and not when it is drawn: a hidden layer is not drawn, and an error waits until it is shown.
            try {
                if (parsePath(l.d as string).every((run) => run.points.length === 0)) fail('d draws nothing');
            } catch (e) {
                fail((e as Error).message);
            }
            break;
        case 'figure': {
            if (!isPair(l.at)) fail('at must be [x, y]: the place on the floor under her');
            if (!(isNum(l.height) && (l.height as number) > 0)) fail('height must be pixels from floor to crown');
            for (const key of ['yaw', 'pitch']) if (l[key] !== undefined && !isNum(l[key])) fail(`${key} must be degrees`);
            if (l.light !== undefined && !(Array.isArray(l.light) && l.light.length === 3 && l.light.every(isNum))) fail('light must be [x, y, z], x right, y up, z toward the viewer');
            const build = l.build as Record<string, unknown> | undefined;
            for (const [key, value] of Object.entries(build ?? {})) {
                if (!['head', 'shoulders', 'chest', 'waist', 'hips', 'limbs'].includes(key)) fail(`build has unknown "${key}"; it takes head, shoulders, chest, waist, hips, limbs`);
                if (!(isNum(value) && (value as number) > 0)) fail(`build ${key} must be positive`);
            }
            const pose = l.pose as Record<string, Record<string, unknown>> | undefined;
            for (const key of Object.keys(pose ?? {})) if (!['rotate', 'move', 'reach'].includes(key)) fail(`pose has unknown "${key}"; it takes rotate, move, reach`);
            for (const [key, list] of Object.entries(pose ?? {})) {
                for (const [joint, value] of Object.entries(list)) {
                    const numbers = key === 'reach' ? (value as { at?: unknown }).at : value;
                    const lengths = key === 'reach' ? [2, 3] : [3];
                    if (!(Array.isArray(numbers) && lengths.includes(numbers.length) && numbers.every(isNum))) fail(`pose ${key} "${joint}" must be ${key === 'reach' ? '{ at: [x, y] or [x, y, z] }' : '[x, y, z]'}`);
                }
            }
            break;
        }
        case 'text':
            if (typeof l.text !== 'string' || !l.text) fail('text must say something');
            if (l.within !== undefined && !(Array.isArray(l.within) && l.within.length === 4 && l.within.every((v) => isNum(v) && v >= 0 && v <= 1))) fail('within must be [left, top, right, bottom], each 0..1');
            if (l.face !== undefined) {
                if (typeof l.face !== 'string') fail('face must name a face of a block, as "id.a"');
            } else if (l.quad !== undefined) {
                if (!(Array.isArray(l.quad) && l.quad.length === 4 && l.quad.every(isPair))) fail('quad must be four [x, y], in order round from the top left');
            } else {
                pair('at');
                if (!(isNum(l.fontSize) && (l.fontSize as number) > 0)) fail('fontSize must be positive, in pixels');
            }
            if (l.font !== undefined && typeof l.font !== 'string') fail('font must be a family name or a font file in the project');
            if (l.align !== undefined && !['left', 'center', 'right'].includes(l.align as string)) fail('align must be left, center or right');
            if (l.tracking !== undefined && !isNum(l.tracking)) fail('tracking must be pixels');
            if (l.thin !== undefined && !(isNum(l.thin) && (l.thin as number) >= 0)) fail('thin must be 0 or more pixels');
            for (const key of ['grain', 'dry']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0 && (l[key] as number) <= 1)) fail(`${key} must be 0..1`);
            if (l.grainScale !== undefined && !(isNum(l.grainScale) && (l.grainScale as number) > 0)) fail('grainScale must be positive');
            if (l.fill === undefined && l.stroke === undefined) fail('it needs a fill or a stroke, or it draws nothing');
            break;
        case 'adjust': {
            const bad = adjustProblem(l.adjust);
            if (bad) fail(`adjust ${bad}`);
            break;
        }
        case 'filter': {
            const bad = filterProblem(l.filter, l.params);
            if (bad) fail(bad);
            break;
        }
        case 'bloom':
            for (const key of ['threshold', 'strength']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more`);
            if (l.threshold !== undefined && (l.threshold as number) > 1) fail('threshold must be 0..1');
            if (l.radius !== undefined && !(isNum(l.radius) && (l.radius as number) > 0)) fail('radius must be positive, in pixels');
            break;
        case 'perspective':
            if (!Array.isArray(l.vanish) || l.vanish.length === 0 || !l.vanish.every(isPair)) fail('vanish must be one or more [x, y]');
            break;
        case 'block': {
            pair('at');
            if (!(isNum(l.height) && (l.height as number) > 0)) fail('height must be pixels, from the corner at its foot up to its top');
            if (!Array.isArray(l.vanish) || l.vanish.length < 1 || l.vanish.length > 2 || !l.vanish.every(isPair)) fail('vanish must be one or two [x, y], where its faces recede to');
            if (!Array.isArray(l.depth) || l.depth.length !== (l.vanish as unknown[]).length || !l.depth.every((d) => isNum(d) && d > 0 && d <= 1)) fail('depth must give each vanishing point how far the face runs toward it, each above 0 and up to 1');
            if (!Array.isArray(l.faces) || l.faces.length !== (l.vanish as unknown[]).length) fail('faces must give one fill for each vanishing point');
            for (const face of l.faces as unknown[]) { const bad = checkFill(face); if (bad) fail(`face ${bad}`); }
            if (l.roof !== undefined) { const bad = checkFill(l.roof); if (bad) fail(`roof ${bad}`); }
            break;
        }
        case 'reflect':
            if (!isNum(l.y) && !(Array.isArray(l.edge) && l.edge.length >= 2 && l.edge.every(isPair))) fail('y must be the line it mirrors about, or edge two or more [x, y] along where things meet the ground');
            for (const key of ['reach', 'ripple', 'smear']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more pixels`);
            break;
        case 'image':
            if (typeof l.src !== 'string' || !l.src) fail('src must be the path of a picture in the project');
            if (l.at !== undefined && !isPair(l.at)) fail('at must be [x, y]');
            if (l.size !== undefined && !isPair(l.size)) fail('size must be [w, h]');
            break;
        case 'paint': {
            if (!Array.isArray(l.strokes)) fail('strokes must be an array, which may start empty');
            if (l.face !== undefined && typeof l.face !== 'string') fail('face must name a face of a block, as "id.a"');
            if (l.from !== undefined && l.from !== 'below') fail('from must be "below"');
            if (l.from !== undefined && (l.fill !== undefined || l.effects !== undefined || l.blend !== undefined)) fail('from "below" works on the picture itself, and takes no fill, effects or blend');
            (l.strokes as Record<string, unknown>[]).forEach((s, n) => {
                const bad = strokeProblem(s);
                if (bad) fail(`stroke ${n} ${bad}`);
            });
            break;
        }
        case 'pixels': {
            if (!Array.isArray(l.rows) || l.rows.length === 0 || !l.rows.every((r) => typeof r === 'string')) fail('rows must be strings, one character a pixel');
            const pal = l.palette as Record<string, unknown> | undefined;
            if (typeof pal !== 'object' || pal === null) fail('palette must be { character: colour }');
            for (const [k, v] of Object.entries(pal!)) {
                if ([...k].length !== 1) fail(`palette key ${JSON.stringify(k)} must be one character`);
                if (!isColor(v)) fail(`palette "${k}" ${JSON.stringify(v)} must be a colour`);
            }
            const known = new Set(Object.keys(pal!));
            const width = (l.rows as string[])[0]!.length;
            (l.rows as string[]).forEach((row, i) => {
                if ([...row].length !== width) fail(`row ${i} is ${[...row].length} wide and row 0 is ${width}: a slip here shifts everything after it`);
                for (const ch of row) if (ch !== '.' && ch !== ' ' && !known.has(ch)) fail(`row ${i} has "${ch}", which is not in the palette; "." and " " are nothing`);
            });
            if (l.scale !== undefined) num('scale', positive);
            if (l.at !== undefined) pair('at');
            break;
        }
        case 'group':
            if (!Array.isArray(l.layers)) fail('a group needs layers');
            (l.layers as Record<string, unknown>[]).forEach((c, i) => checkLayer(c, `${where}.layers[${i}]`, ids));
            break;
        default:
    }
    if (l.fill !== undefined) { const bad = checkFill(l.fill); if (bad) fail(`fill ${bad}`); }
    if (l.stroke !== undefined) {
        const s = l.stroke as Record<string, unknown>;
        if (typeof s !== 'object' || s === null || !isNum(s.width) || (s.width as number) <= 0) fail('stroke must be { color, width, align? }');
        const bad = checkFill(s.color);
        if (bad) fail(`stroke color ${bad}`);
        if (s.align !== undefined && !['center', 'inside', 'outside'].includes(s.align as string)) fail('stroke align must be center, inside or outside');
        if (s.join !== undefined && !['round', 'miter', 'bevel'].includes(s.join as string)) fail('stroke join must be round, miter or bevel');
        if (s.cap !== undefined && !['round', 'butt', 'square'].includes(s.cap as string)) fail('stroke cap must be round, butt or square');
    }
    if (!['group', 'pixels', 'paint', 'figure', 'image', 'text', 'block', 'perspective', 'reflect', 'bloom', 'adjust', 'filter', 'line'].includes(l.shape as string) && l.fill === undefined && l.stroke === undefined && !l.erase) fail('it needs a fill or a stroke, or it draws nothing');
    if (l.from !== undefined && l.shape !== 'paint') fail('from is for a paint layer');
    if (l.guide !== undefined && typeof l.guide !== 'boolean') fail('guide must be true or false');
    if (l.blur !== undefined && !(isNum(l.blur) && (l.blur as number) >= 0)) fail('blur must be 0 or more, in pixels');
    if (l.blur && l.erase) fail('blur does not go with erase; put what cuts in a group with what it cuts, and blur the group');
    if (l.opacity !== undefined && !(isNum(l.opacity) && l.opacity >= 0 && l.opacity <= 1)) fail('opacity must be 0..1');
    if (l.blend !== undefined && !IMAGE_BLENDS.includes(l.blend as ImageBlend)) fail(`blend must be one of ${IMAGE_BLENDS.join(', ')}`);
    for (const key of ['feather', 'clipFeather']) if (l[key] !== undefined && !(isNum(l[key]) && (l[key] as number) >= 0)) fail(`${key} must be 0 or more pixels`);
    if (l.clipGrow !== undefined && !isNum(l.clipGrow)) fail('clipGrow must be pixels, more to grow what it clips to and less to shrink it');
    if (l.clipInvert !== undefined && typeof l.clipInvert !== 'boolean') fail('clipInvert must be true or false');
    if (l.blendIf !== undefined && !(Array.isArray(l.blendIf) && (l.blendIf.length === 2 || l.blendIf.length === 3) && l.blendIf.every((v) => isNum(v) && v >= 0 && v <= 1))) fail('blendIf must be [low, high] or [low, high, softness], each 0..1');
    if (l.mirror !== undefined && l.mirror !== 'x' && l.mirror !== 'y') fail('mirror must be x or y');
    if (l.clip !== undefined && typeof l.clip !== 'string') fail('clip must be a layer id');
    if (l.transform !== undefined) {
        const t = l.transform as Record<string, unknown>;
        for (const key of Object.keys(t)) if (!['translate', 'rotate', 'scale', 'origin'].includes(key)) fail(`transform has an unknown field "${key}"`);
        if (t.translate !== undefined && !isPair(t.translate)) fail('transform.translate must be [x, y]');
        if (t.origin !== undefined && !isPair(t.origin)) fail('transform.origin must be [x, y]');
        if (t.rotate !== undefined && !isNum(t.rotate)) fail('transform.rotate must be degrees');
        if (t.scale !== undefined && !isNum(t.scale) && !isPair(t.scale)) fail('transform.scale must be a number or [x, y]');
    }
    if (l.effects !== undefined) {
        if (!Array.isArray(l.effects)) fail('effects must be an array');
        for (const e of l.effects as Record<string, unknown>[]) {
            if (!['shadow', 'glow', 'innerShadow', 'innerGlow', 'bevel', 'overlay'].includes(e?.type as string)) fail(`an effect has type ${JSON.stringify(e?.type)}; there are shadow, glow, innerShadow, innerGlow, bevel, overlay`);
            if (e.type === 'overlay') { const bad = checkFill(e.fill); if (bad) fail(`effect overlay: fill ${bad}`); }
            if (e.blend !== undefined && !IMAGE_BLENDS.includes(e.blend as ImageBlend)) fail(`effect ${String(e.type)}: blend must be one of ${IMAGE_BLENDS.join(', ')}`);
            if (e.shade !== undefined && !isColor(e.shade)) fail(`effect ${String(e.type)}: shade must be #rgb..#rrggbbaa`);
            for (const key of Object.keys(e)) if (!['type', 'color', 'x', 'y', 'blur', 'opacity', 'size', 'angle', 'depth', 'shade', 'fill', 'blend'].includes(key)) fail(`effect ${String(e.type)} has an unknown field "${key}"`);
            if (e.color !== undefined && !isColor(e.color)) fail(`effect ${String(e.type)}: color must be #rgb..#rrggbbaa`);
            for (const k of ['x', 'y', 'blur', 'opacity', 'size', 'angle', 'depth']) if (e[k] !== undefined && !isNum(e[k])) fail(`effect ${String(e.type)}: ${k} must be a number`);
        }
    }
}

/** The source if it is well formed; otherwise throws, naming the layer and the field. */
export function validateImageSource(raw: unknown): ImageSource {
    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw new Error('an image source must be { size, layers }');
    const s = raw as Record<string, unknown>;
    for (const key of Object.keys(s)) if (!['version', 'size', 'background', 'tile', 'material', 'layers'].includes(key)) throw new Error(`unknown field "${key}"; an image has version, size, background, tile, material, layers`);
    if (s.tile !== undefined && typeof s.tile !== 'boolean') throw new Error('tile must be true or false');
    if (s.version !== undefined && s.version !== IMAGE_SOURCE_VERSION) throw new Error(`version ${String(s.version)} is not one this editor reads (${IMAGE_SOURCE_VERSION})`);
    const [w, h] = typeof s.size === 'number' ? [s.size, s.size] : isPair(s.size) ? (s.size as number[]) : [NaN, NaN];
    if (!Number.isInteger(w) || !Number.isInteger(h) || w! < 1 || h! < 1 || w! > MAX_IMAGE_SIZE || h! > MAX_IMAGE_SIZE) throw new Error(`size must be a whole number or [width, height], 1..${MAX_IMAGE_SIZE}`);
    if (s.background !== undefined && !isColor(s.background)) throw new Error('background must be a colour; leave it out for a transparent picture');
    if (!Array.isArray(s.layers)) throw new Error('layers must be an array');
    const ids = new Set<string>();
    (s.layers as Record<string, unknown>[]).forEach((l, i) => checkLayer(l, `layer ${i}${l?.id ? ` "${String(l.id)}"` : ''}`, ids));
    if (s.material !== undefined) {
        const m = s.material as Record<string, unknown> | null;
        if (typeof m !== 'object' || m === null || Array.isArray(m)) throw new Error('material must be { relief?, height?, roughness?, metal? }');
        for (const key of Object.keys(m)) if (!['relief', 'height', 'roughness', 'metal'].includes(key)) throw new Error(`material has unknown "${key}"; it takes relief, height, roughness, metal`);
        if (m.relief !== undefined && !(isNum(m.relief) && (m.relief as number) >= 0 && (m.relief as number) <= 64)) throw new Error('material.relief must be 0..64, in pixels');
        const drawn = (key: string, v: unknown): void => {
            if (!Array.isArray(v) || v.length === 0) throw new Error(`material.${key} must be layers, one or more`);
            (v as Record<string, unknown>[]).forEach((l, i) => checkLayer(l, `material.${key} layer ${i}${l?.id ? ` "${String(l.id)}"` : ''}`, ids));
        };
        if (m.height !== undefined) drawn('height', m.height);
        for (const key of ['roughness', 'metal']) {
            const v = m[key];
            if (v === undefined) continue;
            if (isNum(v)) { if (v < 0 || v > 1) throw new Error(`material.${key} must be 0..1, or layers`); }
            else drawn(key, v);
        }
    }
    return { version: IMAGE_SOURCE_VERSION, ...(s as unknown as ImageSource) };
}

export type ImageEdit =
    | { op: 'set'; layer: string; fields: Record<string, unknown> }
    | { op: 'insert'; layer: ImageLayer; before?: string; after?: string; into?: string }
    | { op: 'remove'; layer: string }
    | { op: 'move'; layer: string; before?: string; after?: string; into?: string }
    | { op: 'paint'; layer: string; strokes?: readonly ImageMark[]; drop?: number; at?: number; remove?: number }
    | { op: 'wrap'; layers: readonly string[]; group: Partial<ImageLayer> }
    | { op: 'unwrap'; layer: string }
    | {
        op: 'pixels';
        layer: string;
        set?: readonly { row: number; at?: number; text: string }[];
        rect?: readonly { x: number; y: number; w?: number; h?: number; text: string }[];
        palette?: Readonly<Record<string, string | null>>;
    }
    | { op: 'settings'; fields: { size?: ImageSource['size']; background?: string | null; tile?: boolean | null; material?: ImageMaterial | null } };

/** Every stroke width a source draws with, and how many layers use each: what drifts first across a set of icons. */
export function strokeWidths(source: ImageSource): Record<string, number> {
    const out: Record<string, number> = {};
    const walk = (layers: readonly ImageLayer[]): void => {
        for (const l of layers) {
            if (l.stroke) out[String(l.stroke.width)] = (out[String(l.stroke.width)] ?? 0) + 1;
            if (l.layers) walk(l.layers);
        }
    };
    walk(source.layers);
    return out;
}

/** A source with @p edits applied in order, where layers are named by id at any depth. Throws, naming what it could not find. */
export function applyImageEdits(source: ImageSource, edits: readonly ImageEdit[]): ImageSource {
    const clone = JSON.parse(JSON.stringify(source)) as { size: ImageSource['size']; background?: string; version?: number; layers: (ImageLayer & Record<string, unknown>)[] };
    type Row = ImageLayer & Record<string, unknown>;
    const allIds: string[] = [];
    const find = (id: string, list: Row[] = clone.layers): { list: Row[]; index: number } | null => {
        for (let i = 0; i < list.length; i++) {
            if (list[i]!.id === id) return { list, index: i };
            if (list[i]!.layers) {
                const hit = find(id, list[i]!.layers as Row[]);
                if (hit) return hit;
            }
        }
        return null;
    };
    const need = (id: string): { list: Row[]; index: number } => {
        const hit = find(id);
        if (hit) return hit;
        allIds.length = 0;
        const walk = (list: Row[]): void => { for (const l of list) { if (l.id) allIds.push(l.id); if (l.layers) walk(l.layers as Row[]); } };
        walk(clone.layers);
        throw new Error(`no layer "${id}"; ids: ${allIds.join(', ') || '(none: give layers an id to edit them)'}`);
    };
    for (const edit of edits) {
        switch (edit?.op) {
            case 'set': {
                const { list, index } = need(edit.layer);
                for (const [k, v] of Object.entries(edit.fields ?? {})) {
                    if (v === null) delete list[index]![k];
                    else list[index]![k] = v;
                }
                break;
            }
            case 'insert': {
                if (edit.into !== undefined) {
                    const { list, index } = need(edit.into);
                    const group = list[index]!;
                    if (group.shape !== 'group') throw new Error(`layer "${edit.into}" is not a group`);
                    (group.layers as Row[]).push(edit.layer as Row);
                } else if (edit.before !== undefined) {
                    const { list, index } = need(edit.before);
                    list.splice(index, 0, edit.layer as Row);
                } else if (edit.after !== undefined) {
                    const { list, index } = need(edit.after);
                    list.splice(index + 1, 0, edit.layer as Row);
                } else clone.layers.push(edit.layer as Row);
                break;
            }
            case 'remove': {
                const { list, index } = need(edit.layer);
                list.splice(index, 1);
                break;
            }
            case 'move': {
                const given = [edit.before, edit.after, edit.into].filter((v) => v !== undefined);
                if (given.length > 1) throw new Error('move takes one of before, after and into');
                const { list, index } = need(edit.layer);
                const [row] = list.splice(index, 1);
                const within = (l: Row): boolean => l.id === given[0] || ((l.layers as Row[] | undefined) ?? []).some(within);
                if (given.length && within(row!)) {
                    list.splice(index, 0, row!);
                    throw new Error(`layer "${edit.layer}" cannot move next to or into "${String(given[0])}", which is itself or inside it`);
                }
                if (edit.into !== undefined) {
                    const target = need(edit.into);
                    const group = target.list[target.index]!;
                    if (group.shape !== 'group') throw new Error(`layer "${edit.into}" is not a group`);
                    (group.layers as Row[]).push(row!);
                } else if (edit.before !== undefined) {
                    const target = need(edit.before);
                    target.list.splice(target.index, 0, row!);
                } else if (edit.after !== undefined) {
                    const target = need(edit.after);
                    target.list.splice(target.index + 1, 0, row!);
                } else clone.layers.push(row!);
                break;
            }
            case 'paint': {
                const { list, index } = need(edit.layer);
                const layer = list[index]!;
                if (layer.shape !== 'paint') throw new Error(`layer "${edit.layer}" is not paint`);
                const had = layer.strokes as readonly ImageMark[];
                const drop = edit.drop ?? 0;
                if (!Number.isInteger(drop) || drop < 0 || drop > had.length) throw new Error(`layer "${edit.layer}" has ${had.length} strokes: cannot drop ${String(edit.drop)}`);
                const kept = had.slice(0, had.length - drop);
                const at = edit.at ?? kept.length;
                const remove = edit.remove ?? 0;
                if (!Number.isInteger(at) || at < 0 || at > kept.length || !Number.isInteger(remove) || remove < 0 || at + remove > kept.length) throw new Error(`layer "${edit.layer}" has ${kept.length} strokes: cannot replace ${remove} at ${at}`);
                kept.splice(at, remove, ...(edit.strokes ?? []));
                layer.strokes = kept;
                break;
            }
            case 'wrap': {
                if (!Array.isArray(edit.layers) || edit.layers.length === 0) throw new Error('wrap needs layers, the ids to put in the group');
                const found = edit.layers.map((id) => ({ id, ...need(id) }));
                if (found.some((f) => f.list !== found[0]!.list)) throw new Error(`wrap takes layers side by side, and ${edit.layers.join(', ')} are not all in one list`);
                const list = found[0]!.list;
                // Kept in the order they draw, whatever order they were named in: wrapping must not change what is over what.
                const indices = found.map((f) => f.index).sort((a, b) => a - b);
                const children = indices.map((i) => list[i]!);
                for (const i of [...indices].reverse()) list.splice(i, 1);
                list.splice(indices[0]!, 0, { ...edit.group, shape: 'group', layers: children } as Row);
                break;
            }
            case 'unwrap': {
                const { list, index } = need(edit.layer);
                const group = list[index]!;
                if (group.shape !== 'group') throw new Error(`layer "${edit.layer}" is not a group`);
                const kept = ['transform', 'effects', 'opacity', 'blend', 'clip', 'mirror', 'visible'].filter((k) => group[k] !== undefined);
                if (kept.length) throw new Error(`group "${edit.layer}" has ${kept.join(', ')}, which its layers would lose; set them to null first`);
                list.splice(index, 1, ...(group.layers as Row[]));
                break;
            }
            case 'pixels': {
                const { list, index } = need(edit.layer);
                const layer = list[index]!;
                if (layer.shape !== 'pixels') throw new Error(`layer "${edit.layer}" is not pixels`);
                const rows = [...(layer.rows as string[])];
                if (edit.palette) {
                    const palette = { ...(layer.palette as Record<string, string>) };
                    for (const [key, value] of Object.entries(edit.palette)) {
                        if (value === null) delete palette[key];
                        else palette[key] = value;
                    }
                    layer.palette = palette;
                }
                for (const area of edit.rect ?? []) {
                    const [w, h, char] = [area.w ?? 1, area.h ?? 1, [...(area.text ?? '')]];
                    if (char.length !== 1) throw new Error(`a rect in "${edit.layer}" paints one character, not "${area.text}"`);
                    const width = [...rows[0]!].length;
                    if (!(Number.isInteger(area.x) && Number.isInteger(area.y) && Number.isInteger(w) && Number.isInteger(h) && area.x >= 0 && area.y >= 0 && w > 0 && h > 0 && area.x + w <= width && area.y + h <= rows.length)) {
                        throw new Error(`layer "${edit.layer}" is ${width} by ${rows.length}: a rect of ${w} by ${h} at ${area.x}, ${area.y} does not fit`);
                    }
                    for (let y = area.y; y < area.y + h; y++) {
                        const chars = [...rows[y]!];
                        chars.fill(char[0]!, area.x, area.x + w);
                        rows[y] = chars.join('');
                    }
                }
                for (const change of edit.set ?? []) {
                    const row = rows[change.row];
                    if (row === undefined) throw new Error(`layer "${edit.layer}" has rows 0..${rows.length - 1}, not ${change.row}`);
                    const chars = [...row], text = [...change.text], at = change.at ?? 0;
                    if (at < 0 || at + text.length > chars.length) throw new Error(`row ${change.row} of "${edit.layer}" is ${chars.length} wide: ${text.length} at ${at} does not fit`);
                    chars.splice(at, text.length, ...text);
                    rows[change.row] = chars.join('');
                }
                layer.rows = rows;
                break;
            }
            case 'settings':
                if (edit.fields?.size !== undefined) clone.size = edit.fields.size;
                if (edit.fields?.background === null) delete clone.background;
                else if (edit.fields?.background !== undefined) clone.background = edit.fields.background;
                // The whole of each, or none: a relief is replaced with the layers that draw it.
                for (const key of ['tile', 'material'] as const) {
                    if (edit.fields?.[key] === null) delete (clone as Record<string, unknown>)[key];
                    else if (edit.fields?.[key] !== undefined) (clone as Record<string, unknown>)[key] = edit.fields[key];
                }
                break;
            default:
                throw new Error(`an edit has op ${JSON.stringify((edit as { op?: unknown })?.op)}; there are set, insert, remove, move, paint, wrap, unwrap, pixels, settings`);
        }
    }
    return validateImageSource(clone);
}