minimojs 1.0.0-alpha.4 → 1.0.0-alpha.40

package/dist/minimo-format.d.ts

@@ -0,0 +1,632 @@
+/**
+ * @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.
+ */
+/**
+ * An image declared in an asset file, loaded as
+ * `game.loadImage(key, src)` would load it.
+ *
+ * @example
+ * ```json
+ * { "key": "player", "type": "image", "src": "assets/player.png" }
+ * ```
+ */
+export interface ImageAsset {
+    /**
+     * The key sprites and backgrounds use for this image, as in
+     * `new ImageSprite("player")`. Non-empty, with no leading or trailing
+     * spaces, and unique in the whole game: no other entry of any asset file,
+     * of any type, and no `loadImage` or `createTexture` call may use it.
+     */
+    key: string;
+    /** Always `"image"`. */
+    type: "image";
+    /** The image's URL or path, as `game.loadImage(key, src)` takes it. Non-empty. */
+    src: string;
+}
+/**
+ * A sound declared in an asset file, loaded as
+ * `game.loadSound(key, src)` would load it, and played with
+ * `game.playSound(key)`.
+ *
+ * @example
+ * ```json
+ * { "key": "jump", "type": "sound", "src": "assets/jump.mp3" }
+ * ```
+ */
+export interface SoundAsset {
+    /**
+     * The key `game.playSound` uses for this sound. Non-empty, with no leading
+     * or trailing spaces, and unique in the whole game, images included.
+     */
+    key: string;
+    /** Always `"sound"`. */
+    type: "sound";
+    /** The audio file's URL or path, as `game.loadSound(key, src)` takes it. Non-empty. */
+    src: string;
+}
+/**
+ * An entry whose `type` this engine does not support, such as one written for
+ * a newer engine. It is kept as written, so a tool that saves the file does
+ * not drop it, and `game.loadAssets` warns about it and skips it. Its key
+ * still counts toward the game's unique keys.
+ */
+export interface UnknownAsset {
+    /** The entry's key, unique in the whole game like every other. */
+    key: string;
+    /** A type this engine does not support. */
+    type: string;
+    /** The fields of that type, kept unchecked. */
+    [field: string]: unknown;
+}
+/**
+ * The content of an asset file, `*.assets.json`, which declares assets once,
+ * by key, for {@link parseAssetFile} and `game.loadAssets`.
+ *
+ * A game may have any number of asset files, such as `common.assets.json`
+ * and `level3.assets.json`.
+ *
+ * @example
+ * ```json
+ * {
+ *   "format": "minimo-assets",
+ *   "version": 1,
+ *   "assets": [
+ *     { "key": "player", "type": "image", "src": "assets/player.png" },
+ *     { "key": "bat", "type": "image", "src": "assets/bat.png" },
+ *     { "key": "jump", "type": "sound", "src": "assets/jump.mp3" }
+ *   ]
+ * }
+ * ```
+ */
+export interface AssetFile {
+    /** Always `"minimo-assets"`. */
+    format: "minimo-assets";
+    /** The version of the file's shape. Version `1` is the only one so far. */
+    version: 1;
+    /** The declared assets, in file order. */
+    assets: (ImageAsset | SoundAsset | UnknownAsset)[];
+}
+/**
+ * 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 declare function parseAssetFile(json: unknown): AssetFile;
+/**
+ * The type of a design object. Each built-in type maps to one runtime class:
+ * `image` to `ImageSprite`, `emoji` to `EmojiSprite`, `text` to `TextSprite`,
+ * and `background` to `BackgroundLayer`. A `module` object is built by the
+ * optional module it names, such as a `Flame` by the `fire` module.
+ */
+export type DesignObjectType = "image" | "emoji" | "text" | "background" | "module";
+/**
+ * The properties every design object has, whatever its type.
+ *
+ * Every property of a design object is named as its runtime class names it,
+ * so the same names work in code and in files. A property the file omits
+ * keeps the runtime object's default.
+ */
+export interface DesignObjectBase {
+    /**
+     * Required. A UUID unique in the file, such as
+     * `"6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27"`. Tools use it to select, undo,
+     * and compare objects, and it survives renames. It is the only property
+     * with no runtime counterpart.
+     */
+    id: string;
+    /** Optional name, which may repeat. Becomes `Sprite.name`. */
+    name?: string;
+    /** Tags for grouping and for builders. Becomes `Sprite.tags`. Default: `[]`. */
+    tags?: string[];
+    /**
+     * The game's own values, such as a button's action or an enemy's speed.
+     * Always a JSON object, never a bare number or string. Becomes a copy in
+     * `Sprite.data`. Default: `{}`.
+     */
+    data?: Record<string, unknown>;
+}
+/** The properties of every sprite type: `image`, `emoji`, and `text`. */
+export interface DesignSpriteBase extends DesignObjectBase {
+    /** Horizontal center in world space, in pixels. Default: `0`. */
+    x?: number;
+    /** Vertical center in world space, in pixels. Positive is down. Default: `0`. */
+    y?: number;
+    /** Uniform visual scale. Default: `1`. */
+    scale?: number;
+    /** Rotation in degrees, clockwise. Default: `0`. */
+    rotation?: number;
+    /** Mirrors the sprite left to right. Default: `false`. */
+    flipX?: boolean;
+    /** Mirrors the sprite top to bottom. Default: `false`. */
+    flipY?: boolean;
+    /** Opacity, from `0` to `1`. Default: `1`. */
+    alpha?: number;
+    /** Whether the sprite is drawn. Default: `true`. */
+    visible?: boolean;
+    /** Render order; higher layers draw on top. Default: `0`. */
+    layer?: number;
+    /** CSS color, used by monochrome glyphs and by text. Default: `"#000000"`, and `"#ffffff"` for `text`. */
+    color?: string;
+    /** Draws the sprite in screen space, unaffected by scrolling. Default: `false`. */
+    ignoreScroll?: boolean;
+    /** Whether the engine leaves the sprite where it is, as a static obstacle. Default: `false`. */
+    isStatic?: boolean;
+    /** Horizontal velocity in pixels per second. Default: `0`. */
+    vx?: number;
+    /** Vertical velocity in pixels per second. Default: `0`. */
+    vy?: number;
+    /** Gravity multiplier. Default: `0`, immune to gravity. */
+    gravityScale?: number;
+    /** Width of the collision body in pixels, before scale; `null` uses the sprite's width. Default: `null`. */
+    bodyWidth?: number | null;
+    /** Height of the collision body in pixels, before scale; `null` uses the sprite's height. Default: `null`. */
+    bodyHeight?: number | null;
+    /** Horizontal offset of the body's center from the sprite's center, in pixels, before scale. Default: `0`. */
+    bodyOffsetX?: number;
+    /** Vertical offset of the body's center from the sprite's center, in pixels, before scale. Default: `0`. */
+    bodyOffsetY?: number;
+}
+/**
+ * An `ImageSprite` in a design file.
+ *
+ * @example
+ * ```json
+ * { "id": "a93e51b4-6c0d-4f2a-8b17-3e5d9c2f0a61", "name": "play", "type": "image", "imageKey": "btn-play", "x": 360, "y": 700 }
+ * ```
+ */
+export interface DesignImage extends DesignSpriteBase {
+    /** Always `"image"`. */
+    type: "image";
+    /** Required. The key of an image declared in one of the game's asset files. */
+    imageKey: string;
+}
+/**
+ * An `EmojiSprite` in a design file.
+ *
+ * @example
+ * ```json
+ * { "id": "0b9a7c3e-2d4f-4e61-a8c5-7f1e3d2b6a90", "type": "emoji", "sprite": "⭐", "size": 64, "x": 200, "y": 300 }
+ * ```
+ */
+export interface DesignEmoji extends DesignSpriteBase {
+    /** Always `"emoji"`. */
+    type: "emoji";
+    /** Required. The emoji to draw. */
+    sprite: string;
+    /** Base size in pixels. Default: `32`. */
+    size?: number;
+}
+/**
+ * A `TextSprite` in a design file.
+ *
+ * @example
+ * ```json
+ * { "id": "5c2e8f1a-9b3d-4a7e-b6c0-1d4f8e2a7c35", "type": "text", "text": "GAME OVER", "fontSize": 64, "x": 360, "y": 400 }
+ * ```
+ */
+export interface DesignText extends DesignSpriteBase {
+    /** Always `"text"`. */
+    type: "text";
+    /** Required. The text to draw. */
+    text: string;
+    /** Font size in pixels. Default: `16`. */
+    fontSize?: number;
+    /** CSS font family. Default: `"monospace"`. */
+    fontFamily?: string;
+    /** CSS font weight. Default: `"400"`. */
+    fontWeight?: string;
+    /** Line height as a multiple of the font size. Default: `1.2`. */
+    lineHeight?: number;
+    /** Which edge of the text `x` names. Default: `"center"`. */
+    anchorX?: "left" | "center" | "right";
+    /** Which edge of the text `y` names. Default: `"middle"`. */
+    anchorY?: "top" | "middle" | "bottom";
+    /** Alignment of the lines. Default: `"center"`. */
+    textAlign?: "left" | "right" | "center" | "start" | "end";
+    /** Width at which lines wrap, in pixels; `0` never wraps. Default: `0`. */
+    maxWidth?: number;
+    /** Fixed box width in pixels; `0` fits the text. Default: `0`. */
+    fixedWidth?: number;
+    /** Fixed box height in pixels; `0` fits the text. Default: `0`. */
+    fixedHeight?: number;
+    /** Horizontal padding inside the box, in pixels. Default: `2`. */
+    paddingX?: number;
+    /** Vertical padding inside the box, in pixels. Default: `2`. */
+    paddingY?: number;
+    /** CSS color of the box; `null` draws none. Default: `null`. */
+    backgroundColor?: string | null;
+    /** CSS color of the box's border; `null` draws none. Default: `null`. */
+    borderColor?: string | null;
+    /** Width of the box's border in pixels. Default: `0`. */
+    borderWidth?: number;
+    /** Corner radius of the box in pixels. Default: `0`. */
+    cornerRadius?: number;
+    /** CSS color of the text's outline; `null` draws none. Default: `null`. */
+    strokeColor?: string | null;
+    /** Width of the text's outline in pixels. Default: `0`. */
+    strokeWidth?: number;
+}
+/**
+ * A `BackgroundLayer` in a design file. Unlike sprites, its `x` and `y` are
+ * the top-left corner in screen space.
+ *
+ * @example
+ * ```json
+ * { "id": "6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27", "type": "background", "imageKey": "sky" }
+ * ```
+ */
+export interface DesignBackground extends DesignObjectBase {
+    /** Always `"background"`. */
+    type: "background";
+    /** Required. The key of an image declared in one of the game's asset files. */
+    imageKey: string;
+    /** Left edge in screen space, in pixels. Default: `0`. */
+    x?: number;
+    /** Top edge in screen space, in pixels. Default: `0`. */
+    y?: number;
+    /** Width in pixels; `0` uses the canvas width. Default: `0`. */
+    width?: number;
+    /** Height in pixels; `0` uses the canvas height. Default: `0`. */
+    height?: number;
+    /** Opacity, from `0` to `1`. Default: `1`. */
+    alpha?: number;
+    /** Whether the layer is drawn. Default: `true`. */
+    visible?: boolean;
+    /** Order among background layers; all of them draw behind sprites. Default: `0`. */
+    layer?: number;
+    /** How the image fits its rectangle. Default: `"cover"`. */
+    fit?: "none" | "stretch" | "contain" | "cover";
+}
+/**
+ * An object of an optional module in a design file, such as a torch of the
+ * `fire` module. It names its module and its kind, and the module builds it,
+ * so the scene creates the module, such as `new Fire(game)`, before creating
+ * the design's objects. A design holding one is version 3.
+ *
+ * Each module takes only some of the sprite properties and its own
+ * `options`, both listed in {@link designModules}; anything else about the
+ * object, such as what it does while the game plays, is set in code. The
+ * kinds a module places and its options are documented in that module's API.
+ *
+ * @example
+ * ```json
+ * { "id": "3e7b1c9a-5d2f-4a8e-b0c6-9f1d2e4a7b35", "name": "left-torch", "type": "module", "module": "fire", "kind": "torch", "x": 120, "y": 200, "options": { "size": 28 } }
+ * ```
+ */
+export interface DesignModule extends DesignSpriteBase {
+    /** Always `"module"`. */
+    type: "module";
+    /** Required. The module that builds the object, such as `"fire"`: a key of {@link designModules}. */
+    module: string;
+    /** Required. What the module builds, such as `"torch"`: one of its `kinds` in {@link designModules}. */
+    kind: string;
+    /** The module's own settings for the object, such as `{ "size": 28 }`. Default: `{}`. */
+    options?: Record<string, unknown>;
+}
+/** Any object of a design file. Its `type` says which. */
+export type DesignObject = DesignImage | DesignEmoji | DesignText | DesignBackground | DesignModule;
+/**
+ * The content of a design file, `*.design.json`, which a game reads through
+ * {@link Design} and creates with `game.createObject` and
+ * `game.createObjectList`. A design without pages is a {@link DesignFileV1},
+ * one flat list of objects; a design divided into pages is a
+ * {@link DesignFileV2}; a design holding objects of an optional module, with
+ * or without pages, is a {@link DesignFileV3}. All three are current: a
+ * design is written in the lowest version that holds it, so it also loads in
+ * an older MinimoJS whenever it can.
+ */
+export type DesignFile = DesignFileV1 | DesignFileV2 | DesignFileV3;
+/**
+ * A design file without pages: one flat list of objects.
+ *
+ * @example
+ * ```json
+ * {
+ *   "format": "minimo-design",
+ *   "version": 1,
+ *   "objects": [
+ *     { "id": "6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27", "type": "background", "imageKey": "sky" },
+ *     { "id": "a93e51b4-6c0d-4f2a-8b17-3e5d9c2f0a61", "name": "play", "tags": ["button"], "type": "image", "imageKey": "btn-play", "x": 360, "y": 700, "data": { "action": "start" } }
+ *   ]
+ * }
+ * ```
+ */
+export interface DesignFileV1 {
+    /** Always `"minimo-design"`. */
+    format: "minimo-design";
+    /** `1`: the design has no pages. */
+    version: 1;
+    /** The objects, in file order, which is the order they are created and drawn in. */
+    objects: DesignObject[];
+}
+/**
+ * A design file divided into pages. Pages only organize a design, such as
+ * one page per template, or a menu on one page and its button templates on
+ * another; they do not change how an object is created. Read one page's
+ * objects with {@link Design.findAllByPage}.
+ *
+ * @example
+ * ```json
+ * {
+ *   "format": "minimo-design",
+ *   "version": 2,
+ *   "pages": [
+ *     { "id": "0b1d5e7a-3c2f-4d8e-9a61-7f4b2c8e1d05", "name": "Hero", "objects": [
+ *       { "id": "a93e51b4-6c0d-4f2a-8b17-3e5d9c2f0a61", "name": "hero", "type": "image", "imageKey": "hero" }
+ *     ] },
+ *     { "id": "7c4a2e9f-1b3d-4f6a-8c05-2e9d7b1f4a36", "name": "Enemies", "objects": [
+ *       { "id": "c07d9e3f-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "name": "bat", "tags": ["enemy"], "type": "image", "imageKey": "bat" }
+ *     ] }
+ *   ]
+ * }
+ * ```
+ */
+export interface DesignFileV2 {
+    /** Always `"minimo-design"`. */
+    format: "minimo-design";
+    /** `2`: the design is divided into pages. */
+    version: 2;
+    /** The pages, at least one, in file order. */
+    pages: DesignPage[];
+}
+/**
+ * A design file holding objects of an optional module, {@link DesignModule}.
+ * Like the earlier versions, it has either a flat list of `objects` or
+ * `pages`, never both; it is version 3 only because an engine older than
+ * module objects cannot read it.
+ *
+ * @example
+ * ```json
+ * {
+ *   "format": "minimo-design",
+ *   "version": 3,
+ *   "objects": [
+ *     { "id": "6f1c2a0e-3b7d-4c1e-9a52-0d8e4f6b1a27", "type": "background", "imageKey": "dungeon" },
+ *     { "id": "3e7b1c9a-5d2f-4a8e-b0c6-9f1d2e4a7b35", "name": "left-torch", "type": "module", "module": "fire", "kind": "torch", "x": 120, "y": 200 }
+ *   ]
+ * }
+ * ```
+ */
+export interface DesignFileV3 {
+    /** Always `"minimo-design"`. */
+    format: "minimo-design";
+    /** `3`: the design holds objects of an optional module. */
+    version: 3;
+    /** The objects of a design without pages, in file order. Present exactly when `pages` is not. */
+    objects?: DesignObject[];
+    /** The pages of a design divided into pages, in file order. Present exactly when `objects` is not. */
+    pages?: DesignPage[];
+}
+/** One page of a design file with pages: a named group of the design's objects. */
+export interface DesignPage {
+    /**
+     * Required. A UUID unique among the file's pages. Tools use it to keep a
+     * page through a rename; code finds a page by its `name`.
+     */
+    id: string;
+    /**
+     * Required. Unique in the file, not empty, and with no leading or trailing
+     * spaces, such as `"Enemies"`. Code finds a page by it.
+     */
+    name: string;
+    /**
+     * The page's objects, in file order. An object's `id` is unique in the whole
+     * file, across pages.
+     */
+    objects: DesignObject[];
+}
+/**
+ * How one property of a design object is written, for tools that read or edit
+ * designs without the TypeScript types, such as a property panel. See
+ * {@link designObjectProperties}.
+ */
+export interface DesignProperty {
+    /** The property's name, in the file and on the runtime object. */
+    readonly name: string;
+    /**
+     * The JSON type of its value. `"string-list"` is a list of strings, as
+     * `tags`; `"object"` is a JSON object, as `data`.
+     */
+    readonly type: "number" | "string" | "boolean" | "string-list" | "object";
+    /** Whether `null` is accepted besides values of its type, as for `bodyWidth`. */
+    readonly nullable: boolean;
+    /** The only strings accepted, as for `fit`; `null` when any value of its type is. */
+    readonly values: readonly string[] | null;
+    /** Whether every object of its type must have it. A required property has no default. */
+    readonly required: boolean;
+    /**
+     * The runtime object's value when the file omits the property.
+     * `undefined` for a required property, for `name`, and for a module option
+     * whose default depends on the object's kind.
+     */
+    readonly default: unknown;
+}
+/**
+ * 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 declare const designObjectProperties: Readonly<Record<DesignObjectType, readonly DesignProperty[]>>;
+/** One of a module's own options, as a {@link DesignModule}'s `options` holds it. */
+export interface DesignModuleOption extends DesignProperty {
+    /** The smallest number accepted; `null` when there is no lower bound or the option is not a number. */
+    readonly min: number | null;
+    /** The largest number accepted; `null` when there is no upper bound or the option is not a number. */
+    readonly max: number | null;
+}
+/**
+ * What a design may hold of one optional module, for the engine that
+ * validates designs and for tools such as an editor. See {@link designModules}.
+ */
+export interface DesignModuleSchema {
+    /** The module's id, as a {@link DesignModule}'s `module` names it, such as `"fire"`. */
+    readonly module: string;
+    /** The module's file, next to `minimo.js`, such as `"minimo-fire.js"`. */
+    readonly file: string;
+    /**
+     * The class the module exports, which a scene creates with
+     * `new Class(game)` before creating the design's objects, and whose
+     * `update(dt)` advances them, such as `"Fire"`.
+     */
+    readonly className: string;
+    /** The kinds a design can place, such as `"torch"`. The module makes any other kind in code only. */
+    readonly kinds: readonly string[];
+    /**
+     * The sprite properties of {@link DesignSpriteBase} a design may set on the
+     * module's objects, besides `name`, `tags`, and `data`, which every object takes.
+     */
+    readonly properties: readonly string[];
+    /** The module's own options, which `options` may hold. */
+    readonly options: readonly DesignModuleOption[];
+    /**
+     * The number option that sets how big an object is, which an editor's
+     * scale handle changes, such as `"size"`; `null` when a design does not
+     * size the module's objects.
+     */
+    readonly sizeOption: string | null;
+}
+/**
+ * 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 declare const designModules: Readonly<Record<string, DesignModuleSchema>>;
+/**
+ * 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 declare class Design {
+    /**
+     * Every object of the design, as object data, in file order: for a design
+     * with pages, every page's objects, page after page. Passing them to
+     * `game.createObjectList` creates every page at once.
+     */
+    readonly objects: readonly DesignObject[];
+    /**
+     * The design's pages, in file order, each with its objects as object data.
+     * Empty for a design without pages, a version 1 file.
+     */
+    readonly pages: readonly Readonly<DesignPage>[];
+    /**
+     * 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: unknown);
+    /**
+     * 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: string): DesignObject;
+    /**
+     * 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: string): DesignObject[];
+    private pageNamed;
+    /**
+     * Returns the first object whose `name` is `name`, in file order.
+     * Throws an error naming `name` when there is none.
+     */
+    findByName(name: string): DesignObject;
+    /** Returns every object whose `name` is `name`, in file order; an empty list when there is none. */
+    findAllByName(name: string): DesignObject[];
+    /**
+     * Returns the first object whose `tags` include `tag`, in file order.
+     * Throws an error naming `tag` when there is none.
+     */
+    findByTag(tag: string): DesignObject;
+    /** Returns every object whose `tags` include `tag`, in file order; an empty list when there is none. */
+    findAllByTag(tag: string): DesignObject[];
+}