@heroiclands/package-build 22.9.1 → 22.10.0

package/types/engine/address.d.mts

@@ -0,0 +1,452 @@
+/**
+ * A complete Address: four segments, and nothing else.
+ *
+ * `type` is the segment the canonical string carries, after the `doc<type>`
+ * redirect. There is no fifth field recording the written form, because the
+ * written form is a rendering rather than part of the value.
+ *
+ * @typedef {object} AddressTuple
+ * @property {string} package - The owning **content** package.
+ * @property {string} system - The system whose document this addresses, or
+ *   `none`.
+ * @property {string} type - The type segment of the canonical Address.
+ * @property {string} shortcode - The note's `shortcode`.
+ */
+/**
+ * Why a written value is not an Address.
+ *
+ * The vocabulary is shared with the resolvers, so one authored mistake gets one
+ * verdict however many surfaces report it.
+ *
+ * - `not-an-address` — the value does not parse as one, which for body prose is
+ *   an ordinary note name rather than a mistake.
+ * - `no-type` — the `<type>` segment is omitted and the position declares no
+ *   default to fill it in, so nothing says what the value names.
+ * - `unknown-type` — the value is definitely qualified and names no known type.
+ * - `no-content-index` — the package named publishes no content index, so there
+ *   is nothing to resolve the rest of the target against.
+ * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `invalid-segment` — a declared Address contains a malformed segment.
+ * - `no-package` — a declared Address cannot supply its package.
+ * - `invalid-system` — a declared Address cannot supply a registered system.
+ *
+ * @typedef {{reason: string, package?: string}} AddressProblem
+ */
+/**
+ * Every content type whose **prose compiles into a JournalEntry of its own**,
+ * addressed by the virtual `doc<type>` qualifier.
+ *
+ * Every item type, every actor type, every map type, plus `macro` — a macro
+ * note's body documents the script the note also compiles into a Macro, which
+ * is the same shape as an item and its description: one note, two documents,
+ * the prose living in the journals pack.
+ *
+ * **One set, read by the compilers and by the grammar alike.** The journals
+ * pass decides what to compile from it, the link manifest decides what to
+ * publish a `doc<type>` entry for, and the parser decides whether `doc<type>`
+ * is a legal type segment. Held apart, the three drift into a manifest that
+ * asserts documentation nothing compiled, a compiled entry no consumer can
+ * address, or an authored `doc<type>` link that stops parsing. It is composed
+ * exactly once, in `defineConfig`, and read from there — never recomposed at a
+ * call site.
+ *
+ * `doc` notes are absent, for the reason that applies to them alone: a `doc`
+ * note's single document *is* its prose, so there is no second document for a
+ * `doc<type>` address to name.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration.
+ *
+ * @returns {ReadonlySet<string>} The configured doc-carrying types.
+ */
+export function docEntryTypes(): ReadonlySet<string>;
+/**
+ * Whether a content note's type is one whose prose becomes a JournalEntry of
+ * its own.
+ *
+ * @param {string} type - The note's `type` frontmatter.
+ * @returns {boolean} True for an item type, an actor type, a map type and
+ *   `macro`; false for `doc`.
+ */
+export function hasDocEntry(type: string): boolean;
+/**
+ * Reads a qualifier as the **virtual `doc<type>`** form, or reports that it is
+ * not one.
+ *
+ * A document and its documentation are two documents in two packs, so they need
+ * two addresses. `skill-wpnc` is the item; `docskill-wpnc` is the JournalEntry
+ * its prose compiled into, and `docmacro-autoattack` is the same arrangement
+ * for a macro.
+ *
+ * The virtual form exists for a type that carries separate documentation
+ * ({@link docEntryTypes} — the set the journals compiler and the link manifest
+ * read too), **or** for one that routes to the items pack. The second clause
+ * covers the open, unenumerated set: types that compile into items are not
+ * enumerated anywhere, and a foreign package may publish an item type this
+ * build has never heard of. Dropping it would silently unlink every `doc<type>`
+ * address into such a package.
+ *
+ * A **real** type of the same name always wins: the virtual reading is only
+ * consulted for a qualifier no authored note claims.
+ *
+ * @param {string} qualifier - The already-normalised type segment.
+ * @param {Set<string>} types - Every type the content tree contains.
+ * @returns {string|null} The underlying document type, or `null` when the
+ *   qualifier is not a virtual one.
+ */
+export function resolveItemDocType(qualifier: string, types: Set<string>): string | null;
+/**
+ * The vocabularies a written Address is read against.
+ *
+ * These are the tree's, not the position's — every position reads against the
+ * same ones — and they travel beside the defaults so that reading an Address is
+ * one call.
+ *
+ * @typedef {object} AddressVocabulary
+ * @property {Set<string>} [types] - Every type the content tree contains.
+ * @property {Set<string>} [packages] - Every package an Address may name.
+ *   Omitted by callers that resolve within one package, where the fully
+ *   qualified form cannot occur.
+ * @property {Set<string>} [noIndexPackages] - Packages declared
+ *   `contentIndex: false` — a Foundry dependency only, with no fetched index. A
+ *   fully qualified target naming one is refused with `no-content-index` before
+ *   its type is even considered.
+ */
+/**
+ * What a position contributes: the defaults for the segments an author may omit.
+ *
+ * `package` and `system` are always supplied; `type` is supplied only by a
+ * position that accepts exactly one, and a position accepting several declares
+ * none, so a value omitting the `<type>` segment is refused rather than guessed
+ * at.
+ *
+ * @typedef {AddressVocabulary & {package?: string, system?: string,
+ *   type?: string}} AddressDefaults
+ */
+/**
+ * Parse a written Address into the one complete tuple it names.
+ *
+ * **An omitted segment defaults from where the value is written** — it is not a
+ * wildcard, and resolution is not a search. So every short form has exactly one
+ * expansion, computed before anything is looked up, and there is no candidate
+ * set to disambiguate.
+ *
+ * @param {unknown} written - The value as authored, with any Wikilink anchor and
+ *   label already removed.
+ * @param {AddressDefaults} [defaults] - The position's defaults and the tree's
+ *   vocabularies.
+ * @param {{declared?: boolean, legacyShortcodeCase?: boolean}} [options] - A declared Address validates every
+ *   segment and requires complete defaults. Package membership is a separate
+ *   resolution question in this mode; prose recognition keeps its vocabulary checks.
+ *   `legacyShortcodeCase` accepts case-insensitive model Shortcodes while the
+ *   completed tuple contains their canonical lowercase identity.
+ * @returns {AddressTuple|AddressProblem} The complete Address, or why there is
+ *   none.
+ */
+export function parseAddress(written: unknown, defaults?: AddressDefaults, { declared, legacyShortcodeCase }?: {
+    declared?: boolean;
+    legacyShortcodeCase?: boolean;
+}): AddressTuple | AddressProblem;
+/**
+ * Whether a value is an internally parsed Address.
+ * @param {unknown} value - A property value.
+ * @returns {boolean} Whether it is a typed tuple.
+ */
+export function isAddressTuple(value: unknown): boolean;
+/**
+ * Render a complete Address as its canonical string.
+ *
+ * Lowercased, because an Address has one spelling: two names differing only in
+ * case are two names nobody can tell apart.
+ *
+ * @param {AddressTuple} tuple - The complete Address.
+ * @returns {string} `package-system-type-shortcode`.
+ */
+export function renderAddress(tuple: AddressTuple): string;
+/**
+ * Whether the type an Address names is one this position accepts.
+ *
+ * The second of the two questions, and separate from the first because the
+ * accepted **set** is a property of the position while the grammar is not.
+ *
+ * **An accepted type carries its documentation form with it.** A position
+ * accepting `weapongear` accepts `docweapongear`, because the journal that
+ * documents a weapon is the same thing to a position that wanted a weapon — and
+ * a prose address of one *is* the journal, so refusing it would refuse the form
+ * an author most often writes. It is the widening `defineConfig` applies to the
+ * types a package may claim, applied here to the types a position may take.
+ *
+ * @param {AddressTuple} tuple - A parsed Address.
+ * @param {Iterable<string>} allowed - The types this position accepts.
+ * @returns {boolean} True when the Address names one of them.
+ */
+export function acceptsType(tuple: AddressTuple, allowed: Iterable<string>): boolean;
+/**
+ * Apply the defaults to a partial reading, giving a complete Address.
+ *
+ * The three rules of the module note, applied in the order they depend on each
+ * other: the package, then the system the type may fix, then the redirect the
+ * system may force.
+ *
+ * @param {{type: string, shortcode: string, package?: string, system?: string,
+ *   itemDoc?: boolean}} read - A partial reading, as {@link readQualifier}
+ *   returns one.
+ * @param {{package?: string, system?: string}} [where] - The citing context: the
+ *   tree's own content package, and the system of the block the value sits in.
+ * @returns {AddressTuple} The complete Address.
+ */
+export function completeAddress(read: {
+    type: string;
+    shortcode: string;
+    package?: string;
+    system?: string;
+    itemDoc?: boolean;
+}, where?: {
+    package?: string;
+    system?: string;
+}): AddressTuple;
+/**
+ * Expand a written Address to the one canonical Address it names.
+ *
+ * {@link completeAddress} and {@link renderAddress} under one name, for the
+ * index keys and cache keys that hold an Address as a string.
+ *
+ * @param {{type: string, shortcode: string, package?: string, system?: string,
+ *   itemDoc?: boolean}} read - A partial reading, as {@link readQualifier}
+ *   returns one.
+ * @param {{package: string, system?: string}} where - The citing context.
+ * @returns {string} The canonical `package-system-type-shortcode`.
+ */
+export function expandAddress(read: {
+    type: string;
+    shortcode: string;
+    package?: string;
+    system?: string;
+    itemDoc?: boolean;
+}, where: {
+    package: string;
+    system?: string;
+}): string;
+/**
+ * The canonical Address of a document, from its four segments.
+ *
+ * Global uniqueness is what lets a dependency's index merge straight into a
+ * local one: the keys cannot collide by accident, so a key already present on
+ * merge is a real conflict rather than an artefact of two packages sharing a
+ * namespace. `(type, shortcode)` alone is unique only *within* a package, and
+ * two independently authored packages reaching for the same short string is a
+ * matter of time.
+ *
+ * **The system segment.** A package may ship content for more than one system,
+ * and one note then compiles into a document per system — an actor in
+ * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
+ * land on one key, so the address cannot name either of them.
+ *
+ * The value is a system id, or the literal **`none`** for a document no game
+ * system defines: a journal, a macro, a scene, and an item's documentation
+ * journal — which is `none` however many systems the item itself declares,
+ * because it is one journal. `none` rather than `any`, because every segment of
+ * an address is an exact literal and `any` reads as a wildcard, which a
+ * resolver written to that misreading would act on silently; and not `null` or
+ * `~`, both of which are YAML nulls that parse to an absent value and drop the
+ * segment entirely.
+ *
+ * @param {string} pkg - The owning **content** package (`sohl`, `thalorna`) —
+ *   not the Foundry package, which varies per compilation target.
+ * @param {string} system - The system whose document this addresses, or `none`.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {string} `package-system-type-shortcode`, lowercased.
+ */
+export function canonicalKey(pkg: string, system: string, type: string, shortcode: string): string;
+/**
+ * Reads a canonical Address back into its segments.
+ *
+ * **Nothing to read and nothing readable are different answers.** An Address
+ * that cannot be canonical — `harn-adventures-sohl-skill-melee`, five segments,
+ * because the package name carries the separator — yields `null`, while an
+ * absent or blank input yields `undefined`. Both are falsy, so every call site
+ * is unaffected; the distinction is there so a caller reporting "this address is
+ * unreadable" can tell that it has one to report about.
+ *
+ * @param {unknown} key - A canonical Address, or nothing.
+ * @returns {{package: string, system: string, type: string, shortcode: string}
+ *   |null|undefined}
+ *   The segments; `null` when there is a string that is not in canonical form;
+ *   `undefined` when there is no Address at all.
+ */
+export function readCanonicalKey(key: unknown): {
+    package: string;
+    system: string;
+    type: string;
+    shortcode: string;
+} | null | undefined;
+/**
+ * Read a written Address as the **partial** reading, before any default applies.
+ *
+ * The first of the two questions, giving the segments the author supplied and
+ * nothing more. It exists for the callers that still hold a partial; the Address
+ * is completed by {@link completeAddress}, and **nothing an omitted segment does
+ * here is a wildcard.** Every omitted segment expands from the position's
+ * defaults, exactly as the specification's table states, so a short form names
+ * exactly one canonical Address and a lookup finds one entry or none. There is no
+ * candidate set and no ambiguity by construction.
+ *
+ * Two separators are accepted, and they are **not** interchangeable in how
+ * confidently they mark a value as qualified:
+ *
+ * - **`type-shortcode`** and its qualified forms — the canonical spelling.
+ *   Obsidian reads `/` inside a wikilink as a *path* and resolves it against the
+ *   vault's folders, so a slash-qualified link is a broken link in the editor
+ *   where the content is authored.
+ * - **`type/shortcode`** — resolved so that a link written before the vault
+ *   migrated does not silently die. A slash is *unconditionally* a qualifier:
+ *   nothing else uses one, so an unknown type before it is reported rather than
+ *   guessed at. The split is at the **last** slash.
+ *
+ * **Package, system and type are lowercase; the shortcode is not.** A shortcode
+ * is routinely mixed — `Clb`, `LtShoe`, `HsTunic` — and is folded rather than
+ * refused. The three segments in front of it are closed vocabularies with one
+ * spelling each, and accepting `Skill` beside `skill` would bless two ways of
+ * writing one address, so a capital there is reported. It is tested only once
+ * the value *parses*: a note name is full of capitals (`[[Shock State]]`), and
+ * calling that a badly-cased address rather than not an address would name the
+ * wrong mistake.
+ *
+ * @param {string} target - The value as authored, anchor already removed.
+ * @param {Set<string>} types - Every type the content tree contains.
+ * @param {Set<string>} [packages] - Every package an Address may name.
+ * @param {Set<string>} [noIndexPackages] - Packages declared
+ *   `contentIndex: false`.
+ * @returns {{type: string, shortcode: string, itemDoc: boolean,
+ *   package?: string, system?: string, reason?: undefined}
+ *   | AddressProblem | null}
+ *   The partial reading, carrying only the segments written; a `reason` when the
+ *   value is definitely qualified but names no known type, no fetched index or a
+ *   badly-cased segment; or `null` when it is not an Address at all.
+ */
+export function readQualifier(target: string, types: Set<string>, packages?: Set<string>, noIndexPackages?: Set<string>): {
+    type: string;
+    shortcode: string;
+    itemDoc: boolean;
+    package?: string;
+    system?: string;
+    reason?: undefined;
+} | AddressProblem | null;
+export { NO_SYSTEM };
+/**
+ * The one character that separates an Address's segments.
+ *
+ * Named because it is the *grammar*, not an implementation detail: it is what a
+ * change to the address form would move, and what a reader of that change has
+ * to find.
+ *
+ * @type {string}
+ */
+export const ADDRESS_SEPARATOR: string;
+/**
+ * How many segments a canonical Address has, and therefore how many
+ * {@link readCanonicalKey} counts.
+ *
+ * @type {number}
+ */
+export const CANONICAL_KEY_SEGMENTS: number;
+/**
+ * The qualifier prefix that addresses a note's **documentation** rather than
+ * the note's own document: `docskill-wpnc` is the JournalEntry that
+ * `skill-wpnc`'s prose compiled into.
+ *
+ * Every doc-carrying type has a `doc<type>` counterpart, formed by prefix and
+ * never enumerated, so the prefix itself is the whole of that vocabulary.
+ *
+ * @type {string}
+ */
+export const ITEM_DOC_PREFIX: string;
+/**
+ * A complete Address: four segments, and nothing else.
+ *
+ * `type` is the segment the canonical string carries, after the `doc<type>`
+ * redirect. There is no fifth field recording the written form, because the
+ * written form is a rendering rather than part of the value.
+ */
+export type AddressTuple = {
+    /**
+     * - The owning **content** package.
+     */
+    package: string;
+    /**
+     * - The system whose document this addresses, or
+     * `none`.
+     */
+    system: string;
+    /**
+     * - The type segment of the canonical Address.
+     */
+    type: string;
+    /**
+     * - The note's `shortcode`.
+     */
+    shortcode: string;
+};
+/**
+ * Why a written value is not an Address.
+ *
+ * The vocabulary is shared with the resolvers, so one authored mistake gets one
+ * verdict however many surfaces report it.
+ *
+ * - `not-an-address` — the value does not parse as one, which for body prose is
+ *   an ordinary note name rather than a mistake.
+ * - `no-type` — the `<type>` segment is omitted and the position declares no
+ *   default to fill it in, so nothing says what the value names.
+ * - `unknown-type` — the value is definitely qualified and names no known type.
+ * - `no-content-index` — the package named publishes no content index, so there
+ *   is nothing to resolve the rest of the target against.
+ * - `not-lowercase` — a package, system or type segment carries a capital.
+ * - `invalid-segment` — a declared Address contains a malformed segment.
+ * - `no-package` — a declared Address cannot supply its package.
+ * - `invalid-system` — a declared Address cannot supply a registered system.
+ */
+export type AddressProblem = {
+    reason: string;
+    package?: string;
+};
+/**
+ * The vocabularies a written Address is read against.
+ *
+ * These are the tree's, not the position's — every position reads against the
+ * same ones — and they travel beside the defaults so that reading an Address is
+ * one call.
+ */
+export type AddressVocabulary = {
+    /**
+     * - Every type the content tree contains.
+     */
+    types?: Set<string> | undefined;
+    /**
+     * - Every package an Address may name.
+     * Omitted by callers that resolve within one package, where the fully
+     * qualified form cannot occur.
+     */
+    packages?: Set<string> | undefined;
+    /**
+     * - Packages declared
+     * `contentIndex: false` — a Foundry dependency only, with no fetched index. A
+     * fully qualified target naming one is refused with `no-content-index` before
+     * its type is even considered.
+     */
+    noIndexPackages?: Set<string> | undefined;
+};
+/**
+ * What a position contributes: the defaults for the segments an author may omit.
+ *
+ * `package` and `system` are always supplied; `type` is supplied only by a
+ * position that accepts exactly one, and a position accepting several declares
+ * none, so a value omitting the `<type>` segment is refused rather than guessed
+ * at.
+ */
+export type AddressDefaults = AddressVocabulary & {
+    package?: string;
+    system?: string;
+    type?: string;
+};
+import { NO_SYSTEM } from "./systems.mjs";

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

@@ -1,3 +1,4 @@
+/** @typedef {import("./art-slots.mjs").ArtSlot} ArtSlot */
 /**
  * The art slot one key names, or `undefined`.
  *
@@ -6,13 +7,30 @@
  */
 export function artSlot(key: unknown): ArtSlot | undefined;
 /**
- * The address an authored art value names.
+ * The Address an authored art value names, checked against what this position
+ * accepts.
  *
- * @param {string} value - The value as authored.
- * @param {string} defaultType - The type the field declares.
- * @returns {string} A written address, which may be partial.
+ * The two questions {@link module:engine/address} keeps separate: does the
+ * value parse, and is what it names acceptable *here*. {@link parseAddress}
+ * answers the first, taking the slot's own `type` as the default an omitted
+ * segment fills in; {@link acceptsType} answers the second, against the set
+ * the position declares rather than against that same default.
+ *
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type a bare value takes.
+ * @param {Iterable<string>|undefined} accepts - The types this position
+ *   accepts, or `undefined` to accept whatever parses.
+ * @param {import("./address.mjs").AddressDefaults} [vocabulary] - The
+ *   position's remaining defaults and the tree's vocabularies.
+ * @returns {import("./address.mjs").AddressTuple
+ *   |import("./address.mjs").AddressProblem
+ *   |{reason: "not-accepted", type: string}} The Address; a reason it does
+ *   not parse; or `not-accepted` when it parses to a type outside `accepts`.
  */
-export function artTarget(value: string, defaultType: string): string;
+export function artTarget(value: unknown, defaultType: string, accepts: Iterable<string> | undefined, vocabulary?: import("./address.mjs").AddressDefaults): import("./address.mjs").AddressTuple | import("./address.mjs").AddressProblem | {
+    reason: "not-accepted";
+    type: string;
+};
 /**
  * The address space an asset reference resolves against, from a corpus.
  *
@@ -60,12 +78,17 @@ export function assetAddressIndex(records?: readonly object[], { config, foreign
  *   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.
+ * @param {Iterable<string>} [accepts] - The types this position accepts, for a
+ *   position that declares a set narrower than "every asset type" — an art
+ *   slot's. Omitted, any asset type is taken, which is an embed's rule: it
+ *   draws a file, and every asset type is a file.
  * @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}.
+ *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}, or `not-accepted`
+ *   when `accepts` is given and the parsed type falls outside it.
  */
-export function readAssetAddress(index: object, value: unknown, defaultType: string): {
+export function readAssetAddress(index: object, value: unknown, defaultType: string, accepts?: Iterable<string>): {
     record: {
         package: string;
         asset: {
@@ -84,9 +107,10 @@ export function readAssetAddress(index: object, value: unknown, defaultType: str
  * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
  * @param {unknown} value - The value as authored.
  * @param {string} defaultType - The type the field declares.
+ * @param {Iterable<string>} [accepts] - The types this position accepts.
  * @returns {{package: string, asset: {path: string}}|null} The record.
  */
-export function resolveArtRecord(index: object, value: unknown, defaultType: string): {
+export function resolveArtRecord(index: object, value: unknown, defaultType: string, accepts?: Iterable<string>): {
     package: string;
     asset: {
         path: string;
@@ -103,13 +127,19 @@ export function resolveArtRecord(index: object, value: unknown, defaultType: str
  * @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.
+ * @param {Iterable<string>} [accepts] - The types this position accepts.
+ * @returns {{pathname: string|null, resolved: boolean, reason?: string,
+ *   type?: string}} The pathname, and whether an address was actually
+ *   answered — which tells a caller applying a default apart from one whose
+ *   address named nothing. `reason` and `type` carry why, unresolved — in
+ *   particular `not-accepted`, which the caller reports as an error rather
+ *   than falling back silently.
  */
-export function artPathname(index: object, value: unknown, defaultType: string): {
+export function artPathname(index: object, value: unknown, defaultType: string, accepts?: Iterable<string>): {
     pathname: string | null;
     resolved: boolean;
+    reason?: string;
+    type?: string;
 };
 /**
  * The default art address a being's own tags choose, or `null`.
@@ -126,34 +156,30 @@ 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.
+ * their own. A **warning**: nothing in this package or a fetched index answers
+ * the address, so the document falls back to its default art rather than
+ * shipping a path that installs nowhere.
  *
  * @param {string} key - The key that was authored.
- * @param {unknown} value - The value it carried.
- * @param {string} defaultType - The type the field declares.
+ * @param {unknown} value - The value it carried, named exactly as written.
  * @returns {string} The message.
  */
-export function unresolvedArtMessage(key: string, value: unknown, defaultType: string): string;
+export function unresolvedArtMessage(key: string, value: unknown): string;
 /**
- * One art slot: the key a note authors, and the type a bare value takes.
+ * What an art address naming a type this slot does not accept is reported as.
  *
- * @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.
+ * An **error**, not a warning: unlike an address nothing answers, this one
+ * names a real type, and no default art repairs an author asking for a sound
+ * where the slot takes an icon or an image.
  *
- * @type {readonly ArtSlot[]}
+ * @param {string} key - The key that was authored.
+ * @param {unknown} value - The value it carried, named exactly as written.
+ * @param {string} type - The type the address named.
+ * @param {Iterable<string>} accepts - The types this slot accepts.
+ * @returns {string} The message.
  */
-export const ART_SLOTS: readonly ArtSlot[];
+export function unacceptedArtMessage(key: string, value: unknown, type: string, accepts: Iterable<string>): string;
+export { ART_SLOTS } from "./art-slots.mjs";
 /**
  * The art a being falls back to, by the kind it is tagged.
  *
@@ -169,24 +195,4 @@ export const ART_SLOTS: readonly ArtSlot[];
  * @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;
-};
+export type ArtSlot = import("./art-slots.mjs").ArtSlot;

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

@@ -0,0 +1,40 @@
+/**
+ * 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[];
+/**
+ * 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;
+    /**
+     * - The types an authored value may
+     * name. **Not the default** — a faith tradition's profile art is a full
+     * illustration rather than a game icon, so an `icon` slot's default stays
+     * `icon` while its accepted set also takes `image`. A value naming a type
+     * outside it is an error, against this set rather than against `type`.
+     */
+    accepts: readonly string[];
+    /**
+     * - Whether the slot reaches a compiled document.
+     */
+    document: boolean;
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};