@heroiclands/package-build 21.0.0 → 21.2.0

package/sohl/actors.mjs

@@ -46,13 +46,7 @@
  * @module
  */
 
-import {
-    sohlField,
-    resolveName,
-    resolveImg,
-    systemTemplatePriority,
-    folderField,
-} from "../engine/helpers.mjs";
+import { sohlField, resolveName, systemTemplatePriority, folderField } from "../engine/helpers.mjs";
 import { openingMasteryLevel } from "./skill-base.mjs";
 import { SystemActorCompiler, renderSection } from "../engine/actor-compiler.mjs";
 // Which Foundry Actor subtype a note's `type` compiles into. Looked up in the
@@ -63,14 +57,6 @@ import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 // verbatim, and `sohl.img` / `sohl.effects` / `sohl.flags` overriding their
 // shared top-level forms for this system alone.
 import { blockProperty, mergeSystemData } from "../engine/system-block.mjs";
-import { readField, retiredTopLevelKey } from "../engine/field-spec.mjs";
-// The retirement window's reports, shared with the frontmatter lint so the two
-// cannot say different things about the same key.
-import {
-    legacyKeyMessage,
-    locateFrontmatterKey,
-    retiredTopLevelMessage,
-} from "../engine/retired-fields.mjs";
 
 /**
  * The system this pass compiles for — the block its notes write.
@@ -89,38 +75,6 @@ const DEFAULT_IMG = {
     being: "systems/sohl/assets/icons/game-icons/delapouite/person.svg",
 };
 
-/**
- * The being's sheet portrait — the one row of the content format's actor
- * mapping table that is authored rather than derived.
- *
- * **Declared, because the position is not a spelling anyone can guess.** This
- * was read with `blockProperty(fm, SYSTEM, "portrait")`, which knows the block
- * and the note's top level and nothing else — so `data.portrait`, the position
- * the specification names and `sohl-thalorna` writes on 646 beings, was
- * invisible, and `?? defaultImg` on the next line turned every miss into the
- * generic person icon rather than into a complaint. Going through
- * {@link module:engine/field-spec.readField} is what makes the mapping table
- * executable here as it already is for HM3's `data.species`.
- *
- * `img` is deliberately **not** declared beside it: the mapping table keeps a
- * note's token art at the top level, so `blockProperty` is the whole of its
- * resolution and there is no `data.img` to reach for.
- *
- * @type {import("../engine/field-spec.mjs").FieldSpec}
- */
-const PORTRAIT_FIELD = Object.freeze({
-    name: "data.portrait",
-    legacyKey: "portrait",
-    to: "portrait",
-    shape: "path",
-    // The two empties survive, because the caller's `?? defaultImg` is what
-    // tells them apart: `null` and an absent key mean "no art named, default
-    // me", `""` means "ship blank on purpose".
-    read: (raw) => resolveImg(raw),
-    default: null,
-    describe: "Path to the portrait image.",
-});
-
 /**
  * The default art for an actor subtype.
  *
@@ -366,43 +320,16 @@ export class Actors extends SystemActorCompiler {
                 absPath: this.currentNote?.absPath,
             })
         );
-        const defaultImg = defaultActorImg(subType);
+        // The being's own default sits above the subtype's: only the note's
+        // tags say whether it is a person or a creature, and only this pass
+        // reads them.
+        const art = this.actorArt(fm, defaultActorImg(subType));
 
         const items = this.buildEmbeddedItems(itemsMap, id, fm, ctx);
 
         const { value: authoredFolder, isAddress } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress });
 
-        // The two retiring positions a declared field may be read from.
-        // **Warnings**, on the pattern every retirement in this package
-        // follows: the note compiles to the correct document either way, so
-        // reddening a tree over one would refuse before the sweep rather than
-        // after it. What they buy is a count — without one, nothing says which
-        // position a value came from, and a default is indistinguishable from
-        // a miss.
-        const portraitReports = {
-            block: SYSTEM,
-            onLegacyKey: (field) =>
-                this.noteWarn(
-                    legacyKeyMessage(SYSTEM, field),
-                    locateFrontmatterKey(this.currentNote?.absPath, field.legacyKey),
-                ),
-            // Anchored at column 1: the two positions share a spelling here —
-            // `sohl.portrait` and `portrait` — so a locator that took the first
-            // match would point at the block key while the message named the
-            // top-level one.
-            onRetiredTopLevel: (field) =>
-                this.noteWarn(
-                    retiredTopLevelMessage(field),
-                    locateFrontmatterKey(
-                        this.currentNote?.absPath,
-                        retiredTopLevelKey(field),
-                        undefined,
-                        { topLevel: true },
-                    ),
-                ),
-        };
-
         const system = {
             // The frontmatter shortcode is the actor's stable `(type, shortcode)`
             // key — and, for a being that is an archetype, its archetype
@@ -414,11 +341,11 @@ export class Actors extends SystemActorCompiler {
             // with the schema, since an undeclared `system` key is discarded at
             // construction without a warning.
             templatePriority: systemTemplatePriority(fm, ctx),
-            // Nullish, not `||`: a note that names no portrait gets the
-            // subtype's default, one that writes `""` ships blank on purpose.
-            // Resolved through the declaration so `data.portrait` is reached at
-            // all — see {@link PORTRAIT_FIELD}.
-            portrait: readField(PORTRAIT_FIELD, fm, portraitReports) ?? defaultImg,
+            // `system.portrait` is **not** written here. A picture of the
+            // subject is a picture, so a being's portrait is the lead image of
+            // its `{#appearance}` section — which is the markup below — and the
+            // key that used to declare one is not a key. With no authored
+            // source left, the field keeps the schema's own initial.
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };
@@ -470,8 +397,7 @@ export class Actors extends SystemActorCompiler {
         return {
             name,
             type: subType,
-            // Nullish, not `||` — see the portrait above.
-            img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg,
+            img: art.img,
             _id: id,
             system,
             items,
@@ -479,7 +405,7 @@ export class Actors extends SystemActorCompiler {
                 name,
                 displayName: 0,
                 actorLink: false,
-                texture: { src: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg },
+                texture: { src: art.token },
                 width: 1,
                 height: 1,
                 sight: { enabled: false },

package/sohl/infobox.mjs

@@ -67,7 +67,7 @@ import { NOTE_SCHEMAS } from "./note-schemas.mjs";
 import { GEAR_TYPE_TO_KEY } from "./being-info.mjs";
 
 /** What this system's box is called. @type {string} */
-export const SOHL_INFOBOX_TITLE = "SoHL";
+export const SOHL_INFOBOX_TITLE = "Song of Heroic Lands";
 
 /**
  * What a value nobody stated is shown as, where showing nothing would be the

package/sohl/note-schemas.mjs

@@ -146,26 +146,14 @@ const BEING_FIELDS = Object.freeze([
  * business; their authored vocabulary is the same, so they share one
  * declaration rather than three copies that could drift.
  *
- * `img` is the one required field — the compiler refuses a map note without it,
- * since a scene with no background is not a map. It was spelled `image` and
- * read from the `sohl:` block; both were read while the trees were
- * swept; that retirement has since completed and `image` is gone.
+ * `data.bgImage` is the one required piece of art — the compiler refuses a map
+ * note without it, since a scene with no background is not a map. It is
+ * declared in the note vocabulary rather than here, because it is an art slot
+ * like every other and a Scene has no `img` for the shared key to reach.
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
 const MAP_FIELDS = Object.freeze([
-    {
-        name: "img",
-        ...STRING,
-        required: true,
-        // Art is not system-specific — a Scene is a core Foundry document, and
-        // every other note type carries its `img` at the note's top level.
-        shared: true,
-        describe:
-            "The scene's background image. Owned by whichever package its first segment " +
-            "names — `systems/…` and `modules/…` are emitted unchanged, anything else is " +
-            "this package's own and is rooted under its assets.",
-    },
     {
         name: "dimensions",
         ...LIST,

package/types/content-config.d.mts

@@ -66,6 +66,7 @@ export const PACKAGE_KINDS: readonly ["systems", "modules", "documentation"];
 export const DOCUMENTATION_KIND: string;
 export namespace DEFAULT_PATHS {
     let content: "assets/content";
+    let assets: "assets";
     let contentIndex: "build/content-index";
     let packJson: "build/packs-json";
     let stage: "build/stage/packs";
@@ -299,6 +300,12 @@ export type PathsInput = {
      * Content tree root.
      */
     content?: string | undefined;
+    /**
+     * The asset roots' parent — the directory
+     *            holding `icons/`, `images/` and
+     *            `audio/`.
+     */
+    assets?: string | undefined;
     /**
      * Where `content-index` writes this
      *      package's note index. Outbound, and a
@@ -338,6 +345,7 @@ export type PathsInput = {
  */
 export type ResolvedPaths = {
     content: string;
+    assets: string;
     contentIndex: string;
     packJson: string;
     stage: string;

package/types/engine/actor-compiler.d.mts

@@ -182,6 +182,29 @@ export class SystemActorCompiler extends BasePackCompiler {
         itemsSourceDirs?: never[] | undefined;
         foreignSourceDirs?: never[] | undefined;
     });
+    /**
+     * The actor's two pieces of art, resolved, with the being default beneath
+     * them.
+     *
+     * **The default is chosen from the note's tags**, which only a compiler can
+     * read: a `character` falls back to one file and a `creature` to another,
+     * and both are addresses in the package that ships them. A tree whose index
+     * cannot answer that address — a dependency not yet fetched — falls through
+     * to the subtype's own default, so the document is never left with no art.
+     *
+     * `tokenIcon` unset follows `icon`, and the fallback is applied after
+     * resolution rather than before: a note naming an icon and no token icon
+     * means "the token wears the profile art", not "the token wears the
+     * default".
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} fallback - The subtype's own default art path.
+     * @returns {{img: string, token: string}} The two paths.
+     */
+    actorArt(fm: object, fallback: string): {
+        img: string;
+        token: string;
+    };
     /** @type {readonly string[]} */
     itemsSourceDirs: readonly string[];
     foreignSourceDirs: any;
@@ -260,6 +283,12 @@ export class SystemActorCompiler extends BasePackCompiler {
      * every embedded id exactly where it was.
      * Returns null if the descriptor cannot be resolved.
      *
+     * **An entry's `data:` is the authoring container, not a document field.**
+     * Its art slot is read here and the container itself goes no further, so an
+     * entry writing `data.icon` reaches the document as a resolved `img` and an
+     * entry writing none takes its type's default — the same two rules an item
+     * note compiles under, reached by the same functions.
+     *
      * @param {Map<string, object>} itemsMap - The predefined items, by address.
      * @param {string} actorId - The owning actor's id, seeding embedded ids.
      * @param {string} type - The **note** type the reference names.

package/types/engine/art-fields.d.mts

@@ -0,0 +1,192 @@
+/**
+ * The art slot one key names, or `undefined`.
+ *
+ * @param {unknown} key - The key under `data:`.
+ * @returns {ArtSlot|undefined} The slot.
+ */
+export function artSlot(key: unknown): ArtSlot | undefined;
+/**
+ * The address an authored art value names.
+ *
+ * @param {string} value - The value as authored.
+ * @param {string} defaultType - The type the field declares.
+ * @returns {string} A written address, which may be partial.
+ */
+export function artTarget(value: string, defaultType: string): string;
+/**
+ * The address space an asset reference resolves against, from a corpus.
+ *
+ * Shaped exactly as {@link module:engine/wikilinks.buildWikilinkIndex}'s result
+ * is in the parts a resolver reads, so the site, the book and the pack compilers
+ * answer one authored address the same way.
+ *
+ * **The note types belong in `types` as well as the asset ones.** Without them
+ * `being-thorn` does not parse as an address at all, and an embed naming a note
+ * is reported as an unknown type on one surface and as the wrong kind of type on
+ * another — one mistake, two verdicts, which is what the shared vocabulary
+ * exists to prevent.
+ *
+ * @param {readonly object[]} records - The corpus, from
+ *   {@link module:engine/content-index.indexRecordsFor}.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {{index?: Map<string, object>, packages?: Iterable<string>}} [opts.foreign] -
+ *   The vendored indexes a dependency published.
+ * @param {Iterable<string>} [opts.types] - The note types this tree knows.
+ * @returns {object} The index.
+ */
+export function assetAddressIndex(records?: readonly object[], { config, foreign, types }?: {
+    config?: object | undefined;
+    foreign?: {
+        index?: Map<string, object>;
+        packages?: Iterable<string>;
+    } | undefined;
+    types?: Iterable<string> | undefined;
+}): object;
+/**
+ * The asset one authored value names, or why it names none.
+ *
+ * The whole lookup in one place, because two callers need it and they need
+ * different halves of the answer: an art slot needs the record, and an embed
+ * needs to tell an address that resolves to nothing from one that reaches the
+ * wrong *kind* of type. Those are different mistakes with different fixes, and a
+ * single `null` would collapse them into one message.
+ *
+ * Local files answer first and foreign ones after, which is an ordering of maps
+ * rather than a precedence rule: an address carries its own package, so the two
+ * cannot both hold one.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type a bare value takes.
+ * @returns {{record: {package: string, asset: {path: string}}, pathname: string}
+ *   |{record: null, reason: string, type?: string}} The asset and the pathname
+ *   it is at, or a reason from
+ *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}.
+ */
+export function readAssetAddress(index: object, value: unknown, defaultType: string): {
+    record: {
+        package: string;
+        asset: {
+            path: string;
+        };
+    };
+    pathname: string;
+} | {
+    record: null;
+    reason: string;
+    type?: string;
+};
+/**
+ * The index record an art value resolves to, or `null`.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type the field declares.
+ * @returns {{package: string, asset: {path: string}}|null} The record.
+ */
+export function resolveArtRecord(index: object, value: unknown, defaultType: string): {
+    package: string;
+    asset: {
+        path: string;
+    };
+} | null;
+/**
+ * The pathname an art value names, in the form an authored one takes.
+ *
+ * Handing the result to {@link module:engine/helpers.resolveImg} is what puts an
+ * art address and a body image through one ownership rule. The two empties
+ * survive it unchanged: `null` and an absent key mean *no art named, apply the
+ * default*, and `""` means *ship blank on purpose*.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type the field declares.
+ * @returns {{pathname: string|null, resolved: boolean}} The pathname, and
+ *   whether an address was actually answered — which tells a caller applying a
+ *   default apart from one whose address named nothing.
+ */
+export function artPathname(index: object, value: unknown, defaultType: string): {
+    pathname: string | null;
+    resolved: boolean;
+};
+/**
+ * The default art address a being's own tags choose, or `null`.
+ *
+ * `character` means a **person**, not a human, and `creature` everything else;
+ * a being carries exactly one of the two, which is what makes the choice a
+ * lookup rather than a precedence rule.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @returns {string|null} The address, or `null` for a note carrying neither tag.
+ */
+export function beingDefaultArt(fm: object): string | null;
+/**
+ * What an unresolved art address is reported as.
+ *
+ * One wording, so the four compilers that can meet the case do not each invent
+ * their own.
+ *
+ * @param {string} key - The key that was authored.
+ * @param {unknown} value - The value it carried.
+ * @param {string} defaultType - The type the field declares.
+ * @returns {string} The message.
+ */
+export function unresolvedArtMessage(key: string, value: unknown, defaultType: string): string;
+/**
+ * One art slot: the key a note authors, and the type a bare value takes.
+ *
+ * @typedef {object} ArtSlot
+ * @property {string} key - The key under `data:`.
+ * @property {string} type - The asset type a bare shortcode defaults to.
+ * @property {boolean} document - Whether the slot reaches a compiled document.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/**
+ * The four art slots, in the order the specification tabulates them.
+ *
+ * `banner` is the one that reaches no compiled document: it is the page's hero
+ * image, read by the site and by the book's section plates and by nothing else.
+ * That is what `document: false` states, and it is why the inert-art check
+ * skips it — a key that is *meant* to reach no document is not an inert key.
+ *
+ * @type {readonly ArtSlot[]}
+ */
+export const ART_SLOTS: readonly ArtSlot[];
+/**
+ * The art a being falls back to, by the kind it is tagged.
+ *
+ * Both files ship in `sohl`, under `assets/icons/other/`, and both are named
+ * here as addresses rather than as paths for the reason every art reference is:
+ * the address resolves to a record that carries the owning package, so a
+ * package borrowing the default gets the same file the system ships.
+ *
+ * **Only the compiler can choose between them**, because only the compiler
+ * reads the note's tags. A schema default is the last resort beneath this one,
+ * and covers a world document created by hand, which no note describes.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const BEING_DEFAULT_ART: Readonly<Record<string, string>>;
+/**
+ * One art slot: the key a note authors, and the type a bare value takes.
+ */
+export type ArtSlot = {
+    /**
+     * - The key under `data:`.
+     */
+    key: string;
+    /**
+     * - The asset type a bare shortcode defaults to.
+     */
+    type: string;
+    /**
+     * - Whether the slot reaches a compiled document.
+     */
+    document: boolean;
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};

package/types/engine/asset-index.d.mts

@@ -0,0 +1,92 @@
+/**
+ * Read a package's asset trees into index records.
+ *
+ * @param {string} assetsBase - The package's asset directory, the three roots'
+ *   parent. A directory that does not exist yields nothing: a package with no
+ *   art is ordinary.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the trees belong to.
+ * @param {object[]} [options.problems] - Supplied by a **reader**: a file that
+ *   cannot be addressed is pushed here as a diagnostic and skipped. Omitted, it
+ *   throws — the contract the emitter needs, since an index missing an asset
+ *   asserts that the address does not exist.
+ * @returns {Array<Record<string, any>>} One record per addressable file, in walk
+ *   order; the caller imposes the index's total order.
+ * @throws {Error} When a file cannot be addressed and no `problems` array was
+ *   supplied. `file` rides on the error.
+ */
+export function collectAssetRecords(assetsBase: string, { contentPackage, problems }: {
+    contentPackage: string;
+    problems?: object[] | undefined;
+}): Array<Record<string, any>>;
+/**
+ * The file a directory records provenance for its subtree in.
+ *
+ * @type {string}
+ */
+export const PROVENANCE_FILE: string;
+/**
+ * The suffix a per-file provenance sidecar carries.
+ *
+ * Appended to the **whole** filename, extension included — `anvil.svg.yaml`,
+ * not `anvil.yaml` — because the address holds one file whose format is free to
+ * change, and a sidecar named after the address alone would be orphaned the day
+ * an SVG became a WebP without anything saying so.
+ *
+ * @type {string}
+ */
+export const PROVENANCE_SIDECAR_SUFFIX: string;
+/**
+ * One field of the `asset` block.
+ *
+ * @typedef {object} AssetRecordField
+ * @property {string} name - The key inside `asset`.
+ * @property {"walk"|"provenance"} from - Where the value comes from: the walk
+ *   itself, or the provenance record resolved for the address.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/**
+ * Every field an `asset` block carries, in the order it is documented.
+ *
+ * **The emitter builds a record from this list**, rather than from a literal
+ * that a second list somewhere else would have to be kept in step with. So a
+ * field added here is emitted, a field removed here stops being emitted, and the
+ * completeness guard derives what it checks from the same declaration instead of
+ * hand-copying it.
+ *
+ * Every field is always present, blank where nothing states it. A fixed record
+ * shape is what lets a consumer read `asset.license` without branching on
+ * whether the package happened to record one, and blank is the honest answer to
+ * "what does this package say about where this file came from" when it says
+ * nothing.
+ *
+ * @type {readonly AssetRecordField[]}
+ */
+export const ASSET_RECORD_FIELDS: readonly AssetRecordField[];
+/**
+ * The keys a provenance file may declare.
+ *
+ * Derived from {@link ASSET_RECORD_FIELDS} rather than restated, so the file
+ * format and the record cannot disagree about which keys exist.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const PROVENANCE_KEYS: ReadonlySet<string>;
+/**
+ * One field of the `asset` block.
+ */
+export type AssetRecordField = {
+    /**
+     * - The key inside `asset`.
+     */
+    name: string;
+    /**
+     * - Where the value comes from: the walk
+     * itself, or the provenance record resolved for the address.
+     */
+    from: "walk" | "provenance";
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};

package/types/engine/asset-types.d.mts

@@ -0,0 +1,110 @@
+/**
+ * Whether a type name addresses a file rather than a note.
+ *
+ * The one test the rewrite scoping rests on: a rewrite rule may substitute an
+ * asset and nothing else, so a fourth asset type is covered by this answer
+ * rather than by editing a list somewhere else.
+ *
+ * @param {unknown} type - The type name.
+ * @returns {boolean} True for `icon`, `image` or `audio`.
+ */
+export function isAssetType(type: unknown): boolean;
+/**
+ * The asset type a root directory declares, or `undefined`.
+ *
+ * @param {unknown} root - A directory name below `paths.assets`.
+ * @returns {AssetType|undefined} The type it holds.
+ */
+export function assetTypeOfRoot(root: unknown): AssetType | undefined;
+/**
+ * Whether a filename can be an address at all.
+ *
+ * A shortcode is lowercase alphanumerics, so a version string, a hyphen or a
+ * date stamp in a basename means the file cannot be addressed. The build says so
+ * rather than inventing a shortcode for it.
+ *
+ * @param {string} shortcode - The basename with its extension removed.
+ * @returns {boolean} Whether it matches {@link ADDRESS_SEGMENT_PATTERN}.
+ */
+export function isAssetShortcode(shortcode: string): boolean;
+/**
+ * The `<system>` segment every asset address carries.
+ *
+ * Spelled here rather than imported from `engine/systems.mjs` so this module
+ * stays a leaf. The two are held to one value by the address round-trip guard,
+ * which reads both.
+ *
+ * @type {string}
+ */
+export const ASSET_SYSTEM: string;
+/**
+ * File extensions that make a file a picture, lowercase and dot-led.
+ *
+ * Foundry's own `IMAGE_FILE_EXTENSIONS`, because these files are installed into
+ * a Foundry data directory and a format Foundry will not display is not one this
+ * toolchain should hand it an address for.
+ *
+ * @type {readonly string[]}
+ */
+export const IMAGE_EXTENSIONS: readonly string[];
+/**
+ * File extensions that make a file a sound, lowercase and dot-led.
+ *
+ * Foundry's own `AUDIO_FILE_EXTENSIONS`, for the reason above.
+ *
+ * @type {readonly string[]}
+ */
+export const AUDIO_EXTENSIONS: readonly string[];
+/**
+ * One asset type: what it is called, which directory holds it, and which files
+ * in that directory are assets of it.
+ *
+ * @typedef {object} AssetType
+ * @property {string} type - The type name, and the third segment of an address.
+ * @property {string} root - The directory below `paths.assets` that holds it.
+ * @property {readonly string[]} extensions - Lowercase, dot-led.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/**
+ * The three asset types, in address order.
+ *
+ * The directory is named for what it holds and the type for what an address
+ * reaches, so the two differ by a letter and the mapping is **declared** rather
+ * than derived from the name.
+ *
+ * `icon` and `image` are two types rather than one because an icon has to stay
+ * coherent drawn into a 32×32 slot while an image is unbounded — a fitness
+ * property of the asset itself. They therefore have separate shortcode
+ * namespaces, and `icon-anvil` and `image-anvil` are different addresses.
+ *
+ * @type {readonly AssetType[]}
+ */
+export const ASSET_TYPES: readonly AssetType[];
+/**
+ * Every asset type name.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const ASSET_TYPE_NAMES: ReadonlySet<string>;
+/**
+ * One asset type: what it is called, which directory holds it, and which files
+ * in that directory are assets of it.
+ */
+export type AssetType = {
+    /**
+     * - The type name, and the third segment of an address.
+     */
+    type: string;
+    /**
+     * - The directory below `paths.assets` that holds it.
+     */
+    root: string;
+    /**
+     * - Lowercase, dot-led.
+     */
+    extensions: readonly string[];
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};