@heroiclands/package-build 20.7.0 → 21.1.0

package/types/engine/infobox-render.d.mts

@@ -0,0 +1,87 @@
+/**
+ * The default HTML for one link value: an anchor when the medium supplied a
+ * URL, and the text alone otherwise.
+ *
+ * An unresolved reference keeps its words. A page that names something the
+ * index has not heard of is better than a page silently missing a row.
+ *
+ * @param {object} value - A `link` value.
+ * @returns {string} HTML.
+ */
+export function linkToHtml(value: object): string;
+/**
+ * One link value as a Foundry document reference.
+ *
+ * A compendium journal links **inside** Foundry: a website URL on a panel a
+ * player reads at the table sends them out of the game, and a UUID resolves to
+ * the document whether or not the world has imported it. Foundry's enricher
+ * reads the reference out of the page's own HTML, so no markup is needed
+ * around it.
+ *
+ * @param {object} value - A `link` value.
+ * @returns {string} A `@UUID` reference, or the text where there is none.
+ */
+export function linkToUuid(value: object): string;
+/**
+ * Every box as HTML, in the order given.
+ *
+ * @param {readonly object[]} boxes - From `buildInfoboxes`.
+ * @param {object} [options] - Options.
+ * @param {(value: object) => string} [options.link] - How this medium draws a
+ *   link. Defaults to an anchor on the value's `url`.
+ * @returns {string} HTML, empty when there is nothing to draw.
+ */
+export function infoboxesToHtml(boxes: readonly object[], { link }?: {
+    link?: ((value: object) => string) | undefined;
+}): string;
+/**
+ * Whether a section holds anything at all.
+ *
+ * A section with nothing in it is not drawn: rule 4 says an absent field is
+ * absent, and a heading over nothing is the em-dash placeholder in another
+ * form. The declaration answers it — {@link module:engine/infobox.sectionHolds}
+ * — because the same question decides whether a system box carries a statement
+ * instead of sections, and two answers to it would come apart.
+ *
+ * @param {object} section - The section.
+ * @returns {boolean} Whether to draw it.
+ */
+export function sectionHasContent(section: object): boolean;
+/**
+ * One link value as Typst.
+ *
+ * An internal destination — a note the book also prints — is a label
+ * reference, so the link works on paper as a cross-reference and in a PDF
+ * viewer as a jump. Everything else is set as its own words.
+ *
+ * @param {object} value - A `link` value.
+ * @param {Map<string, string>} links - Address slug → the book's anchor.
+ * @param {(anchor: string) => string} labelFor - The anchor's Typst label.
+ * @returns {string} Typst markup.
+ */
+export function linkToTypst(value: object, links: Map<string, string>, labelFor: (anchor: string) => string): string;
+/**
+ * Every box as one Typst panel each, breaking between sections.
+ *
+ * The panel is `breakable: true` and each section inside it is
+ * `breakable: false`, which is what puts a break between `ATTRIBUTES` and
+ * `SKILLS` on a richly-statted character and never inside either.
+ *
+ * @param {readonly object[]} boxes - From `buildInfoboxes`.
+ * @param {object} [options] - Options.
+ * @param {(value: object) => string} [options.link] - How the book draws a link.
+ * @returns {string} Typst markup, empty when there is nothing to draw.
+ */
+export function infoboxesToTypst(boxes: readonly object[], { link }?: {
+    link?: ((value: object) => string) | undefined;
+}): string;
+/**
+ * The Typst definitions an infobox panel is drawn with.
+ *
+ * Emitted once at the head of the book rather than inlined per entry: 2,500
+ * entries each carrying their own rules is a megabyte of repetition, and the
+ * one place a reader changes the panel's appearance should be one place.
+ *
+ * @returns {string} Typst markup.
+ */
+export function infoboxTypstPreamble(): string;

package/types/engine/infobox.d.mts

@@ -0,0 +1,443 @@
+/**
+ * One field's overlay entry, qualified by type where the declaration qualifies
+ * it.
+ *
+ * `<type>.<field>` wins over the bare name, so a spelling two types use for two
+ * quantities can be said differently on each without splitting the overlay.
+ *
+ * @param {Readonly<Record<string, object>>} presentation - The overlay.
+ * @param {string|undefined} type - The note's type.
+ * @param {string} name - The field's declared name.
+ * @returns {object} The entry, or an empty one.
+ */
+export function overlayFor(presentation: Readonly<Record<string, object>>, type: string | undefined, name: string): object;
+/**
+ * Whether a value is a word meaning "nothing here" rather than a value.
+ *
+ * @param {unknown} value - The authored value.
+ * @returns {boolean} Whether it is one of {@link UNSET_VALUES}.
+ */
+export function isUnsetSentinel(value: unknown): boolean;
+/**
+ * Whether a value is worth a row.
+ *
+ * Rule 4: an absent field is absent. `null`, `""` and `[]` are how the corpus
+ * writes "nobody filled this in" — a note that declares every key of its type
+ * and leaves most of them empty is the ordinary shape, not the exception — and
+ * so is a sentinel, which is the same absence written as a word. Judged here
+ * rather than per field, because a sentinel that reaches a page reaches it the
+ * same way whichever box was building the row.
+ *
+ * @param {unknown} value - The authored value.
+ * @returns {boolean} Whether to emit it.
+ */
+export function hasValue(value: unknown): boolean;
+/**
+ * A key as a reader sees it: `healingRate` → `Healing rate`.
+ *
+ * The last dotted segment only — a nested key's container is already said by
+ * the section it sits in, and "Appearance eye color" says it twice.
+ *
+ * @param {string} name - The declared key.
+ * @returns {string} The label.
+ */
+export function humanizeFieldName(name: string): string;
+/**
+ * An enumerated value as a reader sees it: `graying_brown` → `graying brown`.
+ *
+ * @param {unknown} value - The authored value.
+ * @returns {string} The text.
+ */
+export function humanizeValue(value: unknown): string;
+/**
+ * A value as a row shows it.
+ *
+ * A **single lowercase token** is an enumerated value — `male`, `medium`,
+ * `city-state` — and a row reading "male" beside a name reads as a fault
+ * rather than as a value, so its words are capitalised. Anything else is prose
+ * the author wrote and is shown as written: title-casing "a dispossessed
+ * noble" would be this build editing the corpus.
+ *
+ * @param {unknown} value - The authored value.
+ * @returns {string} The text.
+ */
+export function presentValue(value: unknown): string;
+/**
+ * Whether a built value is worth a row.
+ *
+ * Separate from {@link hasValue}, which judges what an author wrote: a `link`
+ * value is a mapping and a `links` value is a list of them, and both are
+ * exactly what the authored form is not.
+ *
+ * @param {string} kind - One of {@link INFOBOX_VALUE_KINDS}.
+ * @param {unknown} value - The built value.
+ * @returns {boolean} Whether to emit the row.
+ */
+export function hasRenderableValue(kind: string, value: unknown): boolean;
+/**
+ * The value kind a `data:` declaration implies.
+ *
+ * Read from the declaration's own shape rather than from the value, so two
+ * notes of one type describe the same field the same way — a one-entry list
+ * and a two-entry list are both `links`.
+ *
+ * @param {object} field - A `DataFieldSpec`.
+ * @param {unknown} value - The authored value, for the shapes the declaration
+ *   makes no claim about.
+ * @returns {string} One of {@link INFOBOX_VALUE_KINDS}.
+ */
+export function valueKindOf(field: object, value: unknown): string;
+/**
+ * One row, with its unit on it.
+ *
+ * **The unit goes on the value, not on the label**, because it belongs to the
+ * quantity rather than to the name of the quantity. A price is 160d and a
+ * weight is 1.1 lbs; splitting that across two cells — `Price (d)` beside
+ * `160` — makes a reader reassemble one fact from two places, and reads worst
+ * in the book, whose label column is a narrow small-caps rule.
+ *
+ * A medium cannot supply it. Appending `d` to a price means knowing which row
+ * is the price, which is the one thing a generic renderer must never know — so
+ * the unit is declared here and travels as part of the value.
+ *
+ * The declared string is appended **verbatim**, which is what lets a symbol
+ * hug its number (`160d`) and a word stand off it (`1.1 lbs`). The row's kind
+ * becomes `text`: a number with a unit on it is no longer a number, and saying
+ * otherwise would invite a medium to format it as one.
+ *
+ * @param {string} kind - The row's kind.
+ * @param {unknown} value - The built value.
+ * @param {string} [unit] - The declared unit, or nothing.
+ * @returns {{kind: string, value: unknown}} The row's kind and value.
+ */
+export function applyUnit(kind: string, value: unknown, unit?: string): {
+    kind: string;
+    value: unknown;
+};
+/**
+ * One reference, resolved as far as the medium's index reaches.
+ *
+ * An unresolved reference keeps its own text rather than being dropped: a page
+ * that names something the index has not heard of is better than a page
+ * silently missing a row.
+ *
+ * @param {unknown} ref - The authored reference — a shortcode or an address.
+ * @param {(ref: unknown, hint?: object) => object|undefined} resolve - The
+ *   medium's resolver.
+ * @param {object} [hint] - What the reference is expected to name, where the
+ *   declaration says: `{type}`. A shortcode is unique within a type and not
+ *   across a tree, so a hint is what stops a region resolving to a polity.
+ * @returns {{text: string, url?: string, uuid?: string, address?: string}} The value.
+ */
+export function linkValue(ref: unknown, resolve: (ref: unknown, hint?: object) => object | undefined, hint?: object): {
+    text: string;
+    url?: string;
+    uuid?: string;
+    address?: string;
+};
+/**
+ * The note infobox: the subject from `data:`, plus the name every note has.
+ *
+ * The rows are {@link NOTE_VOCABULARY}'s declaration for the type, in its
+ * order, minus what {@link NOTE_FIELD_PRESENTATION} withholds and minus every
+ * field the note left empty. A type that declares no `data:` fields still gets
+ * the box, because `Name` is a fact about every note.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} [options] - Options.
+ * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
+ *   reference to `{name, url?, uuid?, address?}`.
+ * @param {object} [options.vocabulary] - The note vocabulary to read.
+ * @param {object} [options.presentation] - The overlay to read.
+ * @returns {object} The box.
+ */
+export function noteInfobox(fm: object, options?: {
+    resolve?: ((ref: unknown) => object | undefined) | undefined;
+    vocabulary?: object | undefined;
+    presentation?: object | undefined;
+}): object;
+/**
+ * Declare one system's half of the infobox.
+ *
+ * The **mechanism** is here and the **declaration** is the system's, which is
+ * the `engine/` ÷ `sohl/` line everywhere else in this package: what a box
+ * looks like is note-format knowledge, and which of a system's fields are
+ * worth a row is that system's.
+ *
+ * A declaration is refused at module evaluation rather than when some note
+ * reaches it: it is a small piece of authored data loaded once per build, so a
+ * mistake in it should stop the build immediately and name the fault.
+ *
+ * @param {object} declaration - The system's declaration.
+ * @param {string} declaration.system - The system id.
+ * @param {string} declaration.title - What the box is called.
+ * @param {Readonly<Record<string, readonly object[]>>} [declaration.fields] -
+ *   Note type → that system's declared field list, read for the generic rows
+ *   section. The same list the compiler obeys, never a copy of it.
+ * @param {Readonly<Record<string, {label?: string, withheld?: string}>>} [declaration.presentation] -
+ *   The presentation overlay: what one of this system's fields is called where
+ *   humanising its key is wrong, and the fields that carry no row at all.
+ *   **Not a second field list** — the fields come from `fields`, and a field
+ *   the overlay does not mention still gets a row, so a field added to the
+ *   system reaches the box with no edit here.
+ * @param {Record<string, (fm: object, ctx: object) => object[]>} [declaration.sections] -
+ *   Note type → a builder returning that type's sections, for a type whose box
+ *   is derived rather than read field by field.
+ * @returns {object} The frozen declaration.
+ * @throws {Error} When it names no system or no title.
+ */
+export function defineInfobox({ system, title, fields, presentation, sections }?: {
+    system: string;
+    title: string;
+    fields?: Readonly<Record<string, readonly object[]>> | undefined;
+    presentation?: Readonly<Record<string, {
+        label?: string;
+        withheld?: string;
+    }>> | undefined;
+    sections?: Record<string, (fm: object, ctx: object) => object[]> | undefined;
+}): object;
+/**
+ * Whether a field's value is the one its own declaration would have supplied.
+ *
+ * _A field answered by its default is a fact about the compiler, not about the
+ * note_ — and that is true of the **value**, not of where it was written. A
+ * corpus writes its defaults out: `improveFlag: false`, `combatCategory: none`
+ * and `initSkillMult: 0` are typed into hundreds of notes that mean nothing by
+ * them, and a row for each says the compiler's word back to a reader who came
+ * for the note's.
+ *
+ * A field declaring no default has nothing to be equal to, so every value it
+ * holds is the note's.
+ *
+ * @param {object} field - The declaration.
+ * @param {unknown} raw - The resolved value.
+ * @returns {boolean} Whether the value is the declaration's own.
+ */
+export function isDeclaredDefault(field: object, raw: unknown): boolean;
+/**
+ * The generic rows section: what this note authors in one system's block.
+ *
+ * Read through the system's own field declaration, in its order, and only
+ * where the note said something the declaration does not already say — a value
+ * equal to the field's own default is the compiler's answer wherever it was
+ * typed.
+ *
+ * A field the **note box** already put on the page is skipped, so the panel
+ * does not say one fact twice. It is what the note box *shows* rather than
+ * what its vocabulary declares: a gear item's weight is declared under `data:`
+ * and authored at `sohl.system.weightBase`, and standing down on the
+ * declaration alone left the fact on no surface at all.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {readonly object[]} fields - The system's field declaration.
+ * @param {object} ctx - `{ block, resolve, resolveField, taken, presentation }`.
+ * @returns {object[]} Zero or one section.
+ */
+export function systemRowsSection(fm: object, fields: readonly object[], { block, resolve, resolveField, taken, presentation }: object): object[];
+/**
+ * Every box a note carries, in the order every medium renders them.
+ *
+ * The note box first — it is the subject itself — then one box per system the
+ * note's type maps to, in the order the maps are declared.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} options - Options.
+ * @param {readonly object[]} options.maps - The document-subtype maps this
+ *   build ships, which decide the box set.
+ * @param {readonly object[]} [options.providers] - The systems' infobox
+ *   declarations, keyed by `system`.
+ * @param {(fm: object, block: string) => boolean} options.carriesBlock -
+ *   Whether the note says anything about a system, which decides
+ *   {@link NOT_AVAILABLE}.
+ * @param {(field: object, fm: object, opts: object) => object} options.resolveField -
+ *   Resolves one declared field against the note.
+ * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
+ *   reference to `{name, url?, uuid?, address?}`.
+ * @param {object} [options.vocabulary] - The note vocabulary to read.
+ * @returns {object[]} The boxes.
+ */
+export function buildInfoboxes(fm: object, options: {
+    maps: readonly object[];
+    providers?: readonly object[] | undefined;
+    carriesBlock: (fm: object, block: string) => boolean;
+    resolveField: (field: object, fm: object, opts: object) => object;
+    resolve?: ((ref: unknown) => object | undefined) | undefined;
+    vocabulary?: object | undefined;
+}): object[];
+/**
+ * Whether a section holds anything a medium would draw.
+ *
+ * Keyed by {@link INFOBOX_LAYOUTS}, so a layout added there is understood here
+ * without a second edit.
+ *
+ * @param {object} section - The section.
+ * @returns {boolean} Whether it holds anything.
+ */
+export function sectionHolds(section: object): boolean;
+/**
+ * The box ids a note's type requires, in order.
+ *
+ * Derived from the same two declarations {@link buildInfoboxes} reads, so the
+ * assertion below compares an emitter's output against the format rather than
+ * against a restatement of it.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} options - `{ maps }`.
+ * @returns {string[]} The ids.
+ */
+export function requiredInfoboxIds(fm: object, { maps }: object): string[];
+/**
+ * Refuse a page carrying anything but the boxes its type maps to.
+ *
+ * _Every page carries exactly the boxes its type maps to_ is the property the
+ * format states and the reason the box set is derived rather than declared.
+ * Asserted where the boxes are emitted, in every medium, so a missing infobox
+ * is a failure rather than something nobody notices — and so is a box for a
+ * system that will compile no document, which is a note claiming a system it
+ * does not reach.
+ *
+ * @param {readonly object[]} boxes - What was built.
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} options - `{ maps, where }`.
+ * @returns {readonly object[]} The boxes, unchanged, so a caller may assert
+ *   inline.
+ * @throws {Error} Naming the note, what is missing and what is extra.
+ */
+export function assertInfoboxSet(boxes: readonly object[], fm: object, { maps, where }?: object): readonly object[];
+/**
+ * How a section arranges what it holds.
+ *
+ * Closed, and keyed by the property the section carries its content in — a
+ * renderer reads one of four keys and needs no other knowledge of the data.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const INFOBOX_LAYOUTS: Readonly<Record<string, string>>;
+/**
+ * What a row's `value` is.
+ *
+ * Closed. `link` and `links` carry `{text, url?, uuid?, address?}` — the three
+ * addresses a medium may need, whichever of them its own index could supply.
+ *
+ * @type {readonly string[]}
+ */
+export const INFOBOX_VALUE_KINDS: readonly string[];
+/**
+ * What a mapped system that produced no document for this note says.
+ *
+ * Stated rather than inferred from an empty block, because an absence is a
+ * poor signal: noticing that something is missing requires already knowing it
+ * should have been there, and a reader meeting one page has no way to know.
+ *
+ * @type {string}
+ */
+export const NOT_AVAILABLE: string;
+/**
+ * What a system that does produce a document, and holds nothing a reader has
+ * not already been shown, says.
+ *
+ * The third state of a system box, and the reason it is stated rather than
+ * drawn as an empty panel: a heading over nothing asserts that something
+ * should have been there. It is not {@link NOT_AVAILABLE} — the system
+ * compiles this note, and a reader told otherwise would go looking for a
+ * document that exists. It is that everything this system holds about the note
+ * is either the subject's own fact, carried by the note box above, or a value
+ * the compiler would have supplied anyway.
+ *
+ * @type {string}
+ */
+export const NOTHING_BEYOND_PROFILE: string;
+/** The note infobox's id, which is not a system id. @type {string} */
+export const NOTE_BOX_ID: string;
+/** The note infobox's title. @type {string} */
+export const NOTE_BOX_TITLE: string;
+/** The note infobox's single section id. @type {string} */
+export const NOTE_SECTION_ID: string;
+/**
+ * What a **duration pair** is called.
+ *
+ * A note states an interval twice over — once as a roll formula and once as a
+ * flat number of seconds — and the declaration names the two by what they hold:
+ * `courseDurationFormula` and `courseDurationBase`. A page wants the thing
+ * being timed and which of the two it is reading.
+ *
+ * Shared by the note box's overlay and by a system's, because the two
+ * declarations spell these fields identically and a reader meeting an
+ * affliction written one way and one written the other should meet one word.
+ *
+ * @type {Readonly<Record<string, {label: string}>>}
+ */
+export const DURATION_LABELS: Readonly<Record<string, {
+    label: string;
+}>>;
+/**
+ * What a gear item's two measured quantities are called, and measured in.
+ *
+ * Price is in pence and weight in pounds throughout the corpus, and the same
+ * fact is authored under `data:` on one note and at its destination path on
+ * another — so both overlays read the one declaration and a reader meets one
+ * word and one unit whichever box the row landed in.
+ *
+ * @type {Readonly<Record<string, {label?: string, unit: string}>>}
+ */
+export const GEAR_UNITS: Readonly<Record<string, {
+    label?: string;
+    unit: string;
+}>>;
+/**
+ * The presentation overlay: what a `data:` field is called, and whether it
+ * belongs in the box at all.
+ *
+ * **This is not a second field list.** The fields come from
+ * {@link NOTE_VOCABULARY}; this says only what the vocabulary cannot — the
+ * label where humanising the key is wrong, the group a field composes into,
+ * and the handful of keys that are not reader-facing.
+ *
+ * Three properties, all optional:
+ *
+ * - `label` — what the row is called. Absent means the key, humanised.
+ * - `withheld` — why the field carries no row. Two reasons only: it is
+ *   machinery — something that steers a build or an interface rather than
+ *   describing the subject — or it is an image, which rule 2 keeps out of the
+ *   box.
+ * - `unit` — what the quantity is measured in, appended to the value verbatim.
+ *   See {@link applyUnit}.
+ * - `group` / `phrase` — the field composes into one row with its group mates
+ *   rather than taking a row of its own. `phrase` turns the value into its
+ *   clause; without one the value stands alone, so a field added to a group
+ *   still appears.
+ *
+ * A key is either a field name or `<type>.<field name>`, and the qualified one
+ * wins. One spelling is not one quantity across the vocabulary: `data.weight`
+ * is a being's body weight, which reads as a clause of its appearance, and a
+ * gear item's mass, which is a row. An overlay keyed on the bare word would
+ * compose a coin's weight into its appearance.
+ *
+ * @type {Readonly<Record<string, {label?: string, withheld?: string,
+ *   unit?: string, group?: string, phrase?: (value: any) => string}>>}
+ */
+export const NOTE_FIELD_PRESENTATION: Readonly<Record<string, {
+    label?: string;
+    withheld?: string;
+    unit?: string;
+    group?: string;
+    phrase?: (value: any) => string;
+}>>;
+/**
+/**
+ * The words a note writes when it means "there is nothing here".
+ *
+ * A corpus states an absence three ways, and only two of them are the absence
+ * of a value: the key is omitted, or it holds the field's own default. The
+ * third is a **sentinel** — a token standing in for the unset state, spelled
+ * however the note happened to spell it. `potency: na` and `category: none`
+ * are not a sodium potion and a category called None; they are two authors
+ * writing "not applicable" in the space a value would go.
+ *
+ * Compared after {@link normalizeToken} strips everything but letters, so
+ * `n/a`, `N/A` and `not applicable` are one word and `none of the above` is
+ * not one of them.
+ *
+ * @type {readonly string[]}
+ */
+export const UNSET_VALUES: readonly string[];

package/types/engine/item-registry.d.mts

@@ -61,11 +61,11 @@ export function itemFields(type: string, system?: string): readonly object[] | u
  * `defaultItemArt` was written for. Only the error's *owner* changed: it now
  * names the registry the consumer declares and can add to.
  *
- * **Resolved by the same rule a note's `img:` is.** The path goes through
- * {@link resolveImg}, so `icons/relic.svg` means the consumer's own asset root
- * in the registry exactly as it does on a note, and an already-served path
- * (`systems/sohl/assets/…`, as every SoHL default is) passes through untouched.
- * One spelling, one meaning, wherever it is written.
+ * **Resolved by the same rule a note's `img:` is.** The pathname goes through
+ * {@link resolveImg}, so `icons/relic.svg` means the consumer's own package in
+ * the registry exactly as it does on a note, and `sohl/assets/…` — as every
+ * SoHL default is written — names the `sohl` package's file wherever it is
+ * compiled. One spelling, one meaning, wherever it is written.
  *
  * @param {string} type - the item type.
  * @param {string} [system] - The system compiling it, where a build declares

package/types/engine/journals.d.mts

@@ -136,9 +136,16 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   entry: a module may ship the same content for two systems, and each pack's
  *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
+ * @param {string} [params.infobox] - The note's infobox, already rendered to
+ *   HTML. Prepended to the entry's first page, which is where the format puts
+ *   it: the box is generated content in document order, before the prose, and
+ *   a Foundry page is narrow enough that inlining it is the only arrangement
+ *   that reads. It is **not** a page of its own — a page is what a UUID
+ *   addresses, and a summary a reader has to navigate to is a summary they do
+ *   not see.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infobox, }: {
     id: string;
     name: string;
     markdown: string;
@@ -146,6 +153,7 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, flags,
     folder?: string | null | undefined;
     flags?: object | undefined;
     stats?: object | undefined;
+    infobox?: string | undefined;
 }): object;
 /**
  * Journals pack compiler.

package/types/engine/note-vocabulary.d.mts

@@ -6,6 +6,33 @@
  * @returns {readonly string[]} The tags, in declaration order.
  */
 export function declaredTags(type: string, groups?: object): readonly string[];
+/**
+ * The declared groups scoped to this type, in declaration order.
+ *
+ * The one reading of `types` that the flattened list and the slot check share,
+ * so the two can never disagree about which groups a `being` is held to.
+ *
+ * @param {string} type - The note's type.
+ * @param {object} [groups] - The grouped declaration.
+ * @returns {object[]} The groups that apply.
+ */
+export function applicableTagGroups(type: string, groups?: object): object[];
+/**
+ * The single-valued slots a note of this type has, in declaration order.
+ *
+ * A group carrying `exclusive` states alternatives rather than attributes, so a
+ * note carrying two of its tags has answered one question twice. Only such a
+ * group is returned: the check has nothing to say about a group whose tags
+ * genuinely accumulate.
+ *
+ * @param {string} type - The note's type.
+ * @param {object} [groups] - The grouped declaration.
+ * @returns {{slot: string, tags: readonly string[]}[]} The slots and their values.
+ */
+export function exclusiveTagGroups(type: string, groups?: object): {
+    slot: string;
+    tags: readonly string[];
+}[];
 /**
  * Whether a note carries a given tag, however the author wrote it.
  *
@@ -143,6 +170,21 @@ export const DRAFT_TAG: "draft";
  * Kind and character are separate groups because one slot could not hold both: a
  * fishing village is a `village` that is `fishing`, and the single-valued field
  * this replaced had to spell it `Fishing Village` as a value of its own.
+ *
+ * **A group carrying `exclusive` is a single-valued slot**, and that is the one
+ * closure a tag vocabulary can make. Its tags are not several things the subject
+ * may be at once — they are the alternative answers to one question, so a note
+ * naming two of them has named none, and both together are refused as an error.
+ * The property is opt-in and changes nothing for a group without it: a place is
+ * freely a `port` and a `town`, and `draft` is orthogonal to everything. The
+ * value is what the slot is called, for the message a reader gets.
+ *
+ * **Closure stops at the slot, and deliberately.** A tag outside an exclusive
+ * group's list does not fill that group's slot and is not refused for failing
+ * to — `tags:` is open and a being tagged `undead` is describing the subject in
+ * the author's own words. What is refused is a near miss of a declared value,
+ * and two values of one slot; there is no third refusal to make without taking
+ * back the openness of the region these tags sit in.
  */
 export const DECLARED_TAGS: Readonly<{
     /** What a place *is*. */
@@ -165,6 +207,15 @@ export const DECLARED_TAGS: Readonly<{
         types: string[];
         tags: readonly string[];
     }>;
+    /**
+     * What kind of being this is — a person, or one of the beasts and made
+     * things. A being is one or the other, so the group is a slot.
+     */
+    beingKind: Readonly<{
+        types: string[];
+        exclusive: "kind";
+        tags: readonly string[];
+    }>;
     /** A note's working state, which any note may carry. */
     state: Readonly<{
         types: null;