minimojs 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/minimo-format.js

@@ -0,0 +1,669 @@
+/**
+ * @module minimojs/format
+ *
+ * The file formats MinimoJS reads: asset files, `*.assets.json`, and design
+ * files, `*.design.json`.
+ *
+ * This module uses no DOM, so tools such as an editor or a validating server
+ * import the same code a game runs: `import { parseAssetFile, Design } from
+ * "minimojs/format"`. Games reach it through `minimo.js`, which re-exports it.
+ */
+/** The `format` value of every asset file. */
+const ASSET_FILE_FORMAT = "minimo-assets";
+/** The newest asset file `version` this engine reads. */
+const ASSET_FILE_VERSION = 1;
+const ASSET_FILE_FIELDS = new Set(["format", "version", "assets"]);
+/** The fields of each supported entry type; `image` and `sound` share theirs. */
+const SRC_ASSET_FIELDS = new Set(["key", "type", "src"]);
+/**
+ * Validates the content of an asset file and returns a copy of it.
+ *
+ * Parsing is strict. It throws an error naming what is wrong for:
+ * - a value that is not an asset file object, or an unknown field anywhere;
+ * - a `format` other than `"minimo-assets"`;
+ * - a `version` newer than this engine reads, or one that is not a positive integer;
+ * - an entry without a string `key` and `type`;
+ * - an empty key, or one with leading or trailing spaces;
+ * - a key repeated in the file, whatever the types of its entries;
+ * - an `image` or `sound` entry without a non-empty string `src`.
+ *
+ * An entry of a type this engine does not support is kept unchanged, without
+ * checking its other fields, so nothing is lost when a tool saves the file.
+ *
+ * @param json - The parsed JSON of a `*.assets.json` file.
+ *
+ * @example
+ * ```ts
+ * import common from "./common.assets.json" with { type: "json" };
+ * const file = parseAssetFile(common);
+ * ```
+ */
+export function parseAssetFile(json) {
+    if (!isPlainObject(json)) {
+        throw assetError("an asset file must be a JSON object.");
+    }
+    rejectUnknownFields(json, ASSET_FILE_FIELDS, "the asset file");
+    if (json.format !== ASSET_FILE_FORMAT) {
+        throw assetError(`"format" must be "${ASSET_FILE_FORMAT}", found ${describe(json.format)}.`);
+    }
+    const version = json.version;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        throw assetError(`"version" must be a positive integer, found ${describe(version)}.`);
+    }
+    if (version > ASSET_FILE_VERSION) {
+        throw assetError(`"version" ${version} is newer than this engine reads (${ASSET_FILE_VERSION}). Use a newer MinimoJS.`);
+    }
+    if (!Array.isArray(json.assets)) {
+        throw assetError(`"assets" must be a list, found ${describe(json.assets)}.`);
+    }
+    const assets = [];
+    const indexByKey = new Map();
+    json.assets.forEach((entry, index) => {
+        const where = `assets[${index}]`;
+        if (!isPlainObject(entry)) {
+            throw assetError(`${where} must be an object, found ${describe(entry)}.`);
+        }
+        const key = entry.key;
+        if (typeof key !== "string") {
+            throw assetError(`${where} must have a string "key", found ${describe(key)}.`);
+        }
+        if (key.length === 0) {
+            throw assetError(`${where} has an empty "key".`);
+        }
+        if (key.trim() !== key) {
+            throw assetError(`${where} has the key "${key}", with leading or trailing spaces.`);
+        }
+        const firstIndex = indexByKey.get(key);
+        if (firstIndex !== undefined) {
+            throw assetError(`the key "${key}" is declared twice, in assets[${firstIndex}] and ${where}.`);
+        }
+        indexByKey.set(key, index);
+        const type = entry.type;
+        if (typeof type !== "string" || type.length === 0) {
+            throw assetError(`${where} ("${key}") must have a string "type", found ${describe(type)}.`);
+        }
+        if (type === "image" || type === "sound") {
+            rejectUnknownFields(entry, SRC_ASSET_FIELDS, `${where} ("${key}")`);
+            const src = entry.src;
+            if (typeof src !== "string" || src.trim().length === 0) {
+                throw assetError(`${where} ("${key}") must have a non-empty string "src", found ${describe(src)}.`);
+            }
+            assets.push({ key, type, src });
+        }
+        else {
+            assets.push({ ...entry, key, type });
+        }
+    });
+    return { format: ASSET_FILE_FORMAT, version: ASSET_FILE_VERSION, assets };
+}
+// ---------------------------------------------------------------------------
+// Design files
+// ---------------------------------------------------------------------------
+/** The `format` value of every design file. */
+const DESIGN_FILE_FORMAT = "minimo-design";
+/** The newest design file `version` this engine reads. */
+const DESIGN_FILE_VERSION = 3;
+function spec(type, defaultValue) {
+    return { type, nullable: false, values: null, required: false, default: defaultValue };
+}
+function requiredString() {
+    return { type: "string", nullable: false, values: null, required: true, default: undefined };
+}
+function nullable(type, defaultValue) {
+    return { type, nullable: true, values: null, required: false, default: defaultValue };
+}
+function oneOf(values, defaultValue) {
+    return { type: "string", nullable: false, values, required: false, default: defaultValue };
+}
+const NAME = { name: spec("string", undefined) };
+const TAGS = { tags: spec("string-list", []) };
+const DATA = { data: spec("object", {}) };
+const SPRITE_SPECS = {
+    ...NAME,
+    ...TAGS,
+    x: spec("number", 0),
+    y: spec("number", 0),
+    scale: spec("number", 1),
+    rotation: spec("number", 0),
+    flipX: spec("boolean", false),
+    flipY: spec("boolean", false),
+    alpha: spec("number", 1),
+    visible: spec("boolean", true),
+    layer: spec("number", 0),
+    color: spec("string", "#000000"),
+    ignoreScroll: spec("boolean", false),
+    isStatic: spec("boolean", false),
+    vx: spec("number", 0),
+    vy: spec("number", 0),
+    gravityScale: spec("number", 0),
+    bodyWidth: nullable("number", null),
+    bodyHeight: nullable("number", null),
+    bodyOffsetX: spec("number", 0),
+    bodyOffsetY: spec("number", 0),
+    ...DATA,
+};
+const IMAGE_SPECS = {
+    imageKey: requiredString(),
+    ...SPRITE_SPECS,
+};
+const EMOJI_SPECS = {
+    sprite: requiredString(),
+    size: spec("number", 32),
+    ...SPRITE_SPECS,
+};
+const TEXT_SPECS = {
+    text: requiredString(),
+    fontSize: spec("number", 16),
+    fontFamily: spec("string", "monospace"),
+    fontWeight: spec("string", "400"),
+    lineHeight: spec("number", 1.2),
+    anchorX: oneOf(["left", "center", "right"], "center"),
+    anchorY: oneOf(["top", "middle", "bottom"], "middle"),
+    textAlign: oneOf(["left", "right", "center", "start", "end"], "center"),
+    maxWidth: spec("number", 0),
+    fixedWidth: spec("number", 0),
+    fixedHeight: spec("number", 0),
+    paddingX: spec("number", 2),
+    paddingY: spec("number", 2),
+    backgroundColor: nullable("string", null),
+    borderColor: nullable("string", null),
+    borderWidth: spec("number", 0),
+    cornerRadius: spec("number", 0),
+    strokeColor: nullable("string", null),
+    strokeWidth: spec("number", 0),
+    ...SPRITE_SPECS,
+    color: spec("string", "#ffffff"),
+};
+const BACKGROUND_SPECS = {
+    imageKey: requiredString(),
+    ...NAME,
+    ...TAGS,
+    x: spec("number", 0),
+    y: spec("number", 0),
+    width: spec("number", 0),
+    height: spec("number", 0),
+    alpha: spec("number", 1),
+    visible: spec("boolean", true),
+    layer: spec("number", 0),
+    fit: oneOf(["none", "stretch", "contain", "cover"], "cover"),
+    ...DATA,
+};
+const MODULE_SPECS = {
+    module: requiredString(),
+    kind: requiredString(),
+    options: spec("object", {}),
+    ...SPRITE_SPECS,
+};
+// `any`: each spec has its own value type, which no longer matters once checked.
+function describeProperties(specs) {
+    return Object.freeze(Object.entries(specs).map(([name, { type, nullable, values, required, default: defaultValue }]) => Object.freeze({ name, type, nullable, values, required, default: defaultValue })));
+}
+/**
+ * Every property each type of design object accepts besides `id` and `type`,
+ * with its JSON type, whether it is required, and its default.
+ *
+ * It is the runtime form of {@link DesignImage}, {@link DesignEmoji},
+ * {@link DesignText}, {@link DesignBackground}, and {@link DesignModule},
+ * which the compiler checks it against, for tools that cannot read TypeScript
+ * types, such as an editor's property panel. `new Design(json)` validates
+ * objects with it. A `module` object takes only the properties its module
+ * lists in {@link designModules}.
+ *
+ * @example
+ * ```ts
+ * for (const property of designObjectProperties.image) {
+ *   console.log(property.name, property.type, property.default);
+ * }
+ * ```
+ */
+export const designObjectProperties = Object.freeze({
+    image: describeProperties(IMAGE_SPECS),
+    emoji: describeProperties(EMOJI_SPECS),
+    text: describeProperties(TEXT_SPECS),
+    background: describeProperties(BACKGROUND_SPECS),
+    module: describeProperties(MODULE_SPECS),
+});
+function option(name, type, defaultValue, { values = null, min = null, max = null } = {}) {
+    return Object.freeze({ name, type, nullable: false, values, required: false, default: defaultValue, min, max });
+}
+function moduleSchema(schema) {
+    return Object.freeze({
+        ...schema,
+        kinds: Object.freeze([...schema.kinds]),
+        properties: Object.freeze([...schema.properties]),
+        options: Object.freeze([...schema.options]),
+    });
+}
+/**
+ * The optional modules whose objects a design can hold, by id, with the kinds
+ * each places, the sprite properties and options it takes, and how a tool
+ * loads it. A design object of any other module, kind, property, or option is
+ * refused: what a design does not hold is set in code.
+ *
+ * A design holds how an object looks when its screen opens. What the game
+ * changes while it plays, such as a flame going out or a die's roll, is the
+ * module's API, used in code on the object the design created.
+ *
+ * @example
+ * ```ts
+ * for (const [id, schema] of Object.entries(designModules)) {
+ *   console.log(id, schema.kinds, schema.options.map((option) => option.name));
+ * }
+ * ```
+ */
+export const designModules = Object.freeze({
+    fire: moduleSchema({
+        module: "fire",
+        file: "minimo-fire.js",
+        className: "Fire",
+        kinds: ["torch", "campfire", "burning", "trail"],
+        // A flame is neither rotated nor scaled, since its particles are placed in
+        // the world: its `size` resizes it.
+        properties: ["x", "y", "alpha", "visible", "layer", "ignoreScroll", "bodyWidth", "bodyHeight", "bodyOffsetX", "bodyOffsetY"],
+        options: [
+            option("size", "number", 32, { min: 4 }),
+            option("intensity", "number", 1, { min: 0, max: 1 }),
+            option("palette", "string", "fire", { values: ["fire", "blue", "green", "purple"] }),
+            option("style", "string", "soft", { values: ["soft", "pixel"] }),
+            option("smoke", "number", undefined, { min: 0, max: 1 }),
+            option("sparks", "number", undefined, { min: 0, max: 1 }),
+            option("smokeColor", "string", "#4a4440"),
+            option("light", "boolean", undefined),
+        ],
+        sizeOption: "size",
+    }),
+    dice: moduleSchema({
+        module: "dice",
+        file: "minimo-dice.js",
+        className: "Dice",
+        kinds: ["d4", "d6", "d8", "d10", "d12", "d20"],
+        // A design places a die; its look, its size, and its value are the game's.
+        properties: ["x", "y"],
+        options: [],
+        sizeOption: null,
+    }),
+});
+/** The properties every module object takes, whatever its module. */
+const MODULE_OBJECT_FIELDS = new Set(["id", "type", "module", "kind", "options", "name", "tags", "data"]);
+/** Checks a module object, already checked as a `module`, against its module's schema. */
+function checkModuleObject(object, label, fail) {
+    const quoted = (names) => names.map((name) => `"${name}"`).join(", ");
+    const moduleId = object.module;
+    const schema = Object.prototype.hasOwnProperty.call(designModules, moduleId) ? designModules[moduleId] : undefined;
+    if (schema === undefined) {
+        throw fail(`${label} belongs to the module "${moduleId}", whose objects a design cannot hold. The modules a design can hold objects of are ${quoted(Object.keys(designModules))}.`);
+    }
+    const kind = object.kind;
+    if (!schema.kinds.includes(kind)) {
+        throw fail(`${label} has the kind "${kind}", which a design cannot place. A "${moduleId}" object is one of ${quoted(schema.kinds)}; anything else the module makes is made in code.`);
+    }
+    for (const field of Object.keys(object)) {
+        if (MODULE_OBJECT_FIELDS.has(field) || schema.properties.includes(field))
+            continue;
+        throw fail(`${label} sets "${field}", which a "${moduleId}" object in a design does not take. It takes ${quoted(schema.properties)}; set anything else in code.`);
+    }
+    const options = (object.options ?? {});
+    for (const [name, value] of Object.entries(options)) {
+        const spec = schema.options.find((candidate) => candidate.name === name);
+        if (spec === undefined) {
+            const known = schema.options.length === 0 ? "takes no options" : `takes the options ${quoted(schema.options.map((candidate) => candidate.name))}`;
+            throw fail(`${label} has the option "${name}", which a "${moduleId}" object in a design does not take. It ${known}; set anything else in code.`);
+        }
+        const inRange = typeof value !== "number" || ((spec.min === null || value >= spec.min) && (spec.max === null || value <= spec.max));
+        if (!isValidValue(value, spec) || !inRange) {
+            throw fail(`${label} has the option "${name}" set to ${describe(value)}, but it must be ${describeExpected(spec)}${describeRange(spec)}.`);
+        }
+    }
+}
+function describeRange(option) {
+    if (option.min !== null && option.max !== null)
+        return ` from ${option.min} to ${option.max}`;
+    if (option.min !== null)
+        return ` of at least ${option.min}`;
+    if (option.max !== null)
+        return ` of at most ${option.max}`;
+    return "";
+}
+const DESIGN_FILE_FIELDS = {
+    1: new Set(["format", "version", "objects"]),
+    2: new Set(["format", "version", "pages"]),
+    3: new Set(["format", "version", "objects", "pages"]),
+};
+const DESIGN_PAGE_FIELDS = new Set(["id", "name", "objects"]);
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PROPERTIES_BY_TYPE = new Map(Object.entries(designObjectProperties).map(([type, properties]) => [
+    type,
+    new Map(properties.map((property) => [property.name, property])),
+]));
+/**
+ * Validates one design object and returns a copy of it. `where` names the
+ * object in errors, such as `objects[3]`.
+ *
+ * @internal
+ */
+export function parseDesignObject(json, where, kind = "design object") {
+    const fail = (message) => new Error(`MinimoJS: Invalid ${kind}: ${message}`);
+    if (!isPlainObject(json)) {
+        throw fail(`${where} must be an object, found ${describe(json)}.`);
+    }
+    const label = typeof json.name === "string" ? `${where} ("${json.name}")` : where;
+    const id = json.id;
+    if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+        throw fail(`${label} must have an "id" that is a UUID, such as "6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27", found ${describe(id)}.`);
+    }
+    const type = json.type;
+    const properties = typeof type === "string" ? PROPERTIES_BY_TYPE.get(type) : undefined;
+    if (properties === undefined) {
+        throw fail(`${label} has the type ${describe(type)}, which is not one of ${Object.keys(designObjectProperties)
+            .map((name) => `"${name}"`)
+            .join(", ")}.`);
+    }
+    const copy = { id, type };
+    for (const [field, value] of Object.entries(json)) {
+        if (field === "id" || field === "type")
+            continue;
+        const property = properties.get(field);
+        if (property === undefined) {
+            throw fail(`${label} has an unknown field "${field}" for the type "${type}".`);
+        }
+        if (!isValidValue(value, property)) {
+            throw fail(`${label} has "${field}" set to ${describe(value)}, but it must be ${describeExpected(property)}.`);
+        }
+        copy[field] = copyJson(value);
+    }
+    for (const property of properties.values()) {
+        if (property.required && !(property.name in copy)) {
+            throw fail(`${label} must have "${property.name}", which every "${type}" object requires.`);
+        }
+    }
+    if (type === "module")
+        checkModuleObject(copy, label, fail);
+    return copy;
+}
+function isValidValue(value, property) {
+    if (value === null)
+        return property.nullable;
+    switch (property.type) {
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "string":
+            return typeof value === "string" && (property.values === null || property.values.includes(value));
+        case "boolean":
+            return typeof value === "boolean";
+        case "string-list":
+            return Array.isArray(value) && value.every((item) => typeof item === "string");
+        case "object":
+            return isPlainObject(value);
+    }
+}
+function describeExpected(property) {
+    const base = property.values !== null
+        ? `one of ${property.values.map((value) => `"${value}"`).join(", ")}`
+        : {
+            number: "a finite number",
+            string: "a string",
+            boolean: "true or false",
+            "string-list": "a list of strings",
+            object: "a JSON object",
+        }[property.type];
+    return property.nullable ? `${base} or null` : base;
+}
+/** Copies JSON lists and objects deeply, so a copy never shares them with its source. */
+function copyJson(value) {
+    if (Array.isArray(value))
+        return value.map(copyJson);
+    if (isPlainObject(value)) {
+        const copy = {};
+        for (const [key, item] of Object.entries(value))
+            copy[key] = copyJson(item);
+        return copy;
+    }
+    return value;
+}
+function parseDesignFile(json) {
+    const fail = (message) => new Error(`MinimoJS: Invalid design: ${message}`);
+    if (!isPlainObject(json)) {
+        throw fail("a design must be a JSON object.");
+    }
+    if (json.format !== DESIGN_FILE_FORMAT) {
+        throw fail(`"format" must be "${DESIGN_FILE_FORMAT}", found ${describe(json.format)}.`);
+    }
+    const version = json.version;
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+        throw fail(`"version" must be a positive integer, found ${describe(version)}.`);
+    }
+    if (version > DESIGN_FILE_VERSION) {
+        throw fail(`"version" ${version} is newer than this engine reads (${DESIGN_FILE_VERSION}). Use a newer MinimoJS.`);
+    }
+    // Every version is current, so none is migrated: version 1 is a design
+    // without pages, version 2 one divided into pages, and version 3 either,
+    // holding objects of an optional module.
+    for (const field of Object.keys(json)) {
+        if (!DESIGN_FILE_FIELDS[version].has(field)) {
+            const hint = field === "pages" ? ` A design with pages has "version" 2.` : field === "objects" ? ` In version 2, objects belong to "pages".` : "";
+            throw fail(`the design has an unknown field "${field}".${hint}`);
+        }
+    }
+    if (version === 3 && "objects" in json === "pages" in json) {
+        throw fail(`a version 3 design has either "objects" or "pages", and this one has ${"objects" in json ? "both" : "neither"}.`);
+    }
+    // An object's id is unique in the whole file, across pages.
+    const whereById = new Map();
+    const parseObjects = (entries, where) => {
+        if (!Array.isArray(entries)) {
+            throw fail(`${where === "" ? "" : `${where}.`}"objects" must be a list, found ${describe(entries)}.`);
+        }
+        return entries.map((entry, index) => {
+            const at = `${where === "" ? "" : `${where}.`}objects[${index}]`;
+            const object = parseDesignObject(entry, at, "design");
+            if (object.type === "module" && version < 3) {
+                throw fail(`${at} is a "module" object, which only a design with "version" 3 holds, so that an older MinimoJS refuses the design by its version.`);
+            }
+            const id = object.id.toLowerCase();
+            const first = whereById.get(id);
+            if (first !== undefined) {
+                throw fail(`the id "${object.id}" is used twice, by ${first} and ${at}.`);
+            }
+            whereById.set(id, at);
+            return object;
+        });
+    };
+    if (version === 1) {
+        return { format: DESIGN_FILE_FORMAT, version: 1, objects: parseObjects(json.objects, "") };
+    }
+    if (version === 3 && "objects" in json) {
+        return { format: DESIGN_FILE_FORMAT, version: 3, objects: parseObjects(json.objects, "") };
+    }
+    if (!Array.isArray(json.pages)) {
+        throw fail(`"pages" must be a list, found ${describe(json.pages)}.`);
+    }
+    if (json.pages.length === 0) {
+        throw fail(`"pages" must hold at least one page. A design without pages has "version" 1 and a top-level "objects".`);
+    }
+    const pageIndexById = new Map();
+    const pageIndexByName = new Map();
+    const pages = json.pages.map((entry, index) => {
+        const where = `pages[${index}]`;
+        if (!isPlainObject(entry)) {
+            throw fail(`${where} must be an object, found ${describe(entry)}.`);
+        }
+        const name = entry.name;
+        const label = typeof name === "string" ? `${where} ("${name}")` : where;
+        for (const field of Object.keys(entry)) {
+            if (!DESIGN_PAGE_FIELDS.has(field)) {
+                throw fail(`${label} has an unknown field "${field}".`);
+            }
+        }
+        const id = entry.id;
+        if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+            throw fail(`${label} must have an "id" that is a UUID, such as "0b1d5e7a-3c2f-4d8e-9a61-7f4b2c8e1d05", found ${describe(id)}.`);
+        }
+        const firstWithId = pageIndexById.get(id.toLowerCase());
+        if (firstWithId !== undefined) {
+            throw fail(`the page id "${id}" is used twice, by pages[${firstWithId}] and ${where}.`);
+        }
+        pageIndexById.set(id.toLowerCase(), index);
+        if (typeof name !== "string" || name.length === 0 || name.trim() !== name) {
+            throw fail(`${where} must have a "name" that is a non-empty string with no leading or trailing spaces, found ${describe(name)}.`);
+        }
+        const firstWithName = pageIndexByName.get(name);
+        if (firstWithName !== undefined) {
+            throw fail(`the page name "${name}" is used twice, by pages[${firstWithName}] and ${where}.`);
+        }
+        pageIndexByName.set(name, index);
+        return { id, name, objects: parseObjects(entry.objects, where) };
+    });
+    return version === 3 ? { format: DESIGN_FILE_FORMAT, version: 3, pages } : { format: DESIGN_FILE_FORMAT, version: 2, pages };
+}
+/**
+ * Returns the first item `match` accepts, in order, or throws an error saying
+ * what was searched, because a name or tag that matches nothing is almost
+ * always a typo.
+ *
+ * @internal
+ */
+export function findFirst(items, match, searched, where) {
+    const found = items.find(match);
+    if (found === undefined) {
+        throw new Error(`MinimoJS: No object ${searched} in ${where}.`);
+    }
+    return found;
+}
+/**
+ * The data of a design file, `*.design.json`, validated: its objects, its
+ * pages, and searches on them. A `Design` needs no game and creates nothing; pass its
+ * objects, or the results of its searches, to `game.createObject` or
+ * `game.createObjectList`. Data alone also serves markers, such as spawn
+ * points, which code reads without creating anything.
+ *
+ * Obtain the file by JSON import. One `Design` can be created any number of
+ * times.
+ *
+ * @example
+ * ```ts
+ * import menuJson from "./menu.design.json" with { type: "json" };
+ *
+ * const menu = new Design(menuJson);
+ *
+ * class MenuScene {
+ *   onCreate() {
+ *     const ui = game.createObjectList(menu.objects);
+ *     this.play = ui.findByName("play");
+ *   }
+ * }
+ * ```
+ *
+ * A design divided into pages, such as a screen on one page and templates on
+ * another, is created one page at a time:
+ *
+ * ```ts
+ * const ui = game.createObjectList(menu.findAllByPage("Menu"));
+ * const bat = game.createObject(menu.findByPage("Bat"));
+ * ```
+ */
+export class Design {
+    /**
+     * Validates a design file's content and keeps a copy of it.
+     *
+     * Parsing is strict. It throws an error naming what is wrong for a value
+     * that is not a design, an unknown field, a `format` other than
+     * `"minimo-design"`, a `version` newer than this engine reads, an object
+     * whose `type` is not one of the built-in types, an `id` that is not a UUID
+     * or is used twice, a value of the wrong type, a missing required property,
+     * a `data` that is not a JSON object, a page without a UUID `id` or with
+     * a missing, padded, or repeated `name`, and a `module` object in a design
+     * older than version 3 or with a module, kind, property, or option that
+     * {@link designModules} does not list.
+     *
+     * @param json - The content of a `*.design.json` file. See {@link DesignFile}.
+     */
+    constructor(json) {
+        const file = parseDesignFile(json);
+        const pages = "pages" in file ? file.pages : undefined;
+        if (pages === undefined) {
+            this.pages = Object.freeze([]);
+            this.objects = Object.freeze(("objects" in file ? file.objects : undefined) ?? []);
+        }
+        else {
+            this.pages = Object.freeze(pages.map((page) => Object.freeze({ ...page, objects: Object.freeze(page.objects) })));
+            this.objects = Object.freeze(pages.flatMap((page) => page.objects));
+        }
+    }
+    /**
+     * Returns the first object of the page named `name`, in file order, such
+     * as a page holding one template. Throws an error naming the page when the
+     * design has no page with that name, or the page has no objects.
+     */
+    findByPage(name) {
+        const page = this.pageNamed(name);
+        if (page.objects.length === 0) {
+            throw new Error(`MinimoJS: The page "${name}" of the design has no objects.`);
+        }
+        return page.objects[0];
+    }
+    /**
+     * Returns every object of the page named `name`, in file order; an empty
+     * list for an empty page. Throws an error naming the page when the design
+     * has no page with that name, because a page name that matches nothing is
+     * almost always a typo.
+     */
+    findAllByPage(name) {
+        return [...this.pageNamed(name).objects];
+    }
+    pageNamed(name) {
+        const page = this.pages.find((candidate) => candidate.name === name);
+        if (page === undefined) {
+            const known = this.pages.length === 0 ? "it has no pages" : `its pages are ${this.pages.map((p) => `"${p.name}"`).join(", ")}`;
+            throw new Error(`MinimoJS: No page named "${name}" in the design; ${known}.`);
+        }
+        return page;
+    }
+    /**
+     * Returns the first object whose `name` is `name`, in file order.
+     * Throws an error naming `name` when there is none.
+     */
+    findByName(name) {
+        return findFirst(this.objects, (object) => object.name === name, `named "${name}"`, "the design");
+    }
+    /** Returns every object whose `name` is `name`, in file order; an empty list when there is none. */
+    findAllByName(name) {
+        return this.objects.filter((object) => object.name === name);
+    }
+    /**
+     * Returns the first object whose `tags` include `tag`, in file order.
+     * Throws an error naming `tag` when there is none.
+     */
+    findByTag(tag) {
+        return findFirst(this.objects, (object) => object.tags?.includes(tag) === true, `tagged "${tag}"`, "the design");
+    }
+    /** Returns every object whose `tags` include `tag`, in file order; an empty list when there is none. */
+    findAllByTag(tag) {
+        return this.objects.filter((object) => object.tags?.includes(tag) === true);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rejectUnknownFields(value, allowed, where) {
+    for (const field of Object.keys(value)) {
+        if (!allowed.has(field)) {
+            throw assetError(`${where} has an unknown field "${field}".`);
+        }
+    }
+}
+function describe(value) {
+    if (value === undefined)
+        return "nothing";
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "a list";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "object")
+        return "an object";
+    return String(value);
+}
+function assetError(message) {
+    return new Error(`MinimoJS: Invalid asset file: ${message}`);
+}