@heroiclands/package-build 22.25.0 → 22.27.0

package/types/engine/content-alerts.d.mts

@@ -0,0 +1,62 @@
+/** Read alerts outside code examples, retaining inclusive source line ranges.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanAlerts(source: string): {
+    blocks: {
+        start: number;
+        end: number;
+        depth: number;
+        type: string;
+        title: any;
+        id: string;
+        classes: never[];
+        attributes: {
+            [k: string]: any;
+        };
+        body: string;
+    }[];
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};
+/** Render alert wrappers while preserving ordinary Markdown and note footnotes.
+ * @param {string} source - Authored Markdown.
+ * @param {"web"|"foundry"} [target="web"] - Publishing surface.
+ */
+export function renderAlerts(source: string, target?: "web" | "foundry"): {
+    markdown: string;
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};
+/** Mark alert blockquotes and remove their marker before inline parsing.
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function alertMarkdownPlugin(md: typeof import("markdown-it")): void;
+/** Alert titles and static icons shared by all publishing surfaces. */
+export const ALERT_TYPES: Readonly<{
+    note: {
+        title: string;
+        icon: string;
+        svg: string;
+    };
+    tip: {
+        title: string;
+        icon: string;
+        svg: string;
+    };
+    important: {
+        title: string;
+        icon: string;
+        svg: string;
+    };
+    warning: {
+        title: string;
+        icon: string;
+        svg: string;
+    };
+}>;

package/types/engine/content-blocks.d.mts

@@ -67,20 +67,13 @@ export function renderBlocks(source: string, target: "foundry" | "web"): {
 export function renderWithheldSections(source: string): string;
 /** The blocks an author may open, with the heading each takes by default. */
 export const BLOCK_NAMES: Readonly<{
-    info: "Info";
     secret: "Secret";
-    warn: "Warn";
 }>;
 /**
- * Blocks that may hold another named block.
+ * Container fences whose bodies are scanned and rendered recursively.
  *
- * A box inside a GM-only section is a real thing to write — the section is a
- * container for whatever the GM reads, boxes included — so a `secret` holds one
- * and the box stays inside it. A box inside a box is noise, so `info` and `warn`
- * hold no named block and a second opener inside one is a finding.
- *
- * Exported because a renderer has to know it: the body of a container is read
- * for blocks of its own, and the body of a box is not.
+ * A secret may hold general divs; a general div may hold another div or a
+ * secret. A secret nested directly within another secret is refused.
  *
  * @type {readonly string[]}
  */

package/types/engine/content-embeds.d.mts

@@ -49,7 +49,7 @@ export function resolveEmbed(index: object, embed: ParsedEmbed): {
  * The role an address's asset declares, read through the same resolution an
  * embed's address takes.
  *
- * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * This is the lookup a captioned item's `map` counter reaches through —
  * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` — for
  * an address still in its authored form, before {@link resolveEmbeds} has
  * rewritten it into the ordinary image every surface renders.

package/types/engine/content-figures.d.mts

@@ -1,21 +1,15 @@
 /** Number a sequence of figures with counters shared across documents. */
 export function numberFigures(figures: any, counts: any): any;
 /**
- * Read every `:::figure` fence in a body.
- *
- * SQL fences are expanded before this pass, so their output is a table.
- *
- * @param {string} source - A note body with expanded tables.
+ * Read leading captions and their following blocks outside literal fences.
+ * Historical figure API names remain for caption references and consumers.
+ * @param {string} source - The authored or expanded note body.
  * @param {object} [options] - Options.
- * @param {(address: string) => string|undefined} [options.resolveRole] - From
- *   a picture's address to the role its asset declares, so a picture whose
- *   asset declares `role: map` counts as `map` rather than `figure`. Omitted,
- *   every picture counts as `figure` — the same reading a role other than
- *   `map` gets.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - Asset role lookup.
  * @returns {{figures: Array<{id: string, slug: string, caption: string,
- *   hasCaption: boolean, classes: string[], kind: string, number: number,
- *   label: string, line: number, bodyStart: number, bodyEnd: number,
- *   captionStart: number, captionEnd: number, close: number}>,
+ *   hasCaption: boolean, classes: string[], attributes: Record<string,string>,
+ *   kind: string, numbered: boolean, number: number, label: string, line: number,
+ *   bodyStart: number, bodyEnd: number, captionStart: number, captionEnd: number, close: number}>,
  *   errors: Array<{line: number, column: number, message: string}>}}
  */
 export function scanFigures(source: string, { resolveRole }?: {
@@ -27,7 +21,9 @@ export function scanFigures(source: string, { resolveRole }?: {
         caption: string;
         hasCaption: boolean;
         classes: string[];
+        attributes: Record<string, string>;
         kind: string;
+        numbered: boolean;
         number: number;
         label: string;
         line: number;
@@ -44,7 +40,7 @@ export function scanFigures(source: string, { resolveRole }?: {
     }>;
 };
 /**
- * Render figure fences as HTML, leaving other Markdown untouched.
+ * Render leading captions and their next blocks as HTML, leaving other Markdown untouched.
  *
  * A code, table or prose figure's contents are left as Markdown inside the
  * wrapper, blank-line separated from its tags exactly as
@@ -84,6 +80,7 @@ export function renderFigureBlocks(source: string, renderMarkdown?: (markdown: s
 /** A figure's automatically determined kind, and the word that labels it. */
 export const FIGURE_NAMES: Readonly<{
     code: "Code";
+    example: "Example";
     table: "Table";
     figure: "Figure";
     map: "Map";
@@ -91,12 +88,8 @@ export const FIGURE_NAMES: Readonly<{
     prose: "Prose";
 }>;
 /**
- * The classes a figure takes.
- *
- * `.border` states that the captioned thing is drawn inside a border, and each
- * medium owns what that means. The vocabulary is closed: a class absent from it
- * is a finding naming the class.
- *
+ * Historical built-in presentation classes, retained for theme consumers.
+ * Captions now accept arbitrary classes through the shared attribute grammar.
  * @type {readonly string[]}
  */
 export const FIGURE_CLASSES: readonly string[];

package/types/engine/content-images.d.mts

@@ -67,7 +67,7 @@ export function escapeHtml(text: string): string;
  * function, so the two cannot drift into styling the same directive through
  * different class names.
  *
- * **No `<figcaption>` is emitted here.** A `:::figure` fence draws its own
+ * **No `<figcaption>` is emitted here.** A captioned item draws its own
  * label and authored caption around whatever this returns; the alt text stays
  * on the `img` element alone.
  *

package/types/engine/content-poetry.d.mts

@@ -17,3 +17,35 @@ export function inlineVerse(text: any): string;
  * definitions remain in scope. The span carries the indent for each line.
  */
 export function poetryMarkdown(body: any): string;
+/** Read poetry code fences; start/end are inclusive zero-based source lines.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanPoetry(source: string): {
+    blocks: {
+        end: number;
+        body: string;
+        start: number;
+        fence: string;
+        name: string;
+        attributes: {};
+        id: string;
+        classes: never[];
+        indent: string;
+    }[];
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};
+/** Replace verse fences with HTML wrappers whose body remains inline Markdown.
+ * @param {string} source - Authored Markdown.
+ */
+export function renderPoetry(source: string): {
+    markdown: string;
+    errors: {
+        line: number;
+        column: number;
+        message: string;
+    }[];
+};

package/types/engine/content-spans.d.mts

@@ -0,0 +1,18 @@
+/** Add bracket spans after recognized Markdown links and footnotes.
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function spanMarkdownPlugin(md: typeof import("markdown-it")): void;
+/** Read span anchors and located attribute diagnostics outside literal code.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanSpans(source: string): {
+    spans: any[];
+    errors: any[];
+};
+/** Emit span tags while leaving their inline content as Markdown for Hugo.
+ * @param {string} source - Authored Markdown.
+ */
+export function renderSpans(source: string): {
+    markdown: string;
+    errors: any[];
+};

package/types/engine/holdings.d.mts

@@ -1,157 +1,114 @@
+/** @typedef {{title:string,url?:string,type:string,subType?:string}} HoldingsEntry */
 /**
- * A `parents` or `domains` value as the shortcodes it names, in order,
- * empties dropped and repeats collapsed.
- *
- * @param {unknown} value - The authored value — a list, or a lone entry.
- * @returns {string[]} The shortcodes.
+ * @typedef {object} HoldingsNode
+ * @property {string} shortcode
+ * @property {"place"|"affiliation"} type
+ * @property {string} [subType]
+ * @property {string} title
+ * @property {string} [url]
+ * @property {string} [package] Owning content package.
+ * @property {string} [system] Own document system.
+ * @property {string} [canonical] Full own Address.
+ * @property {string} [governmentSystem] Affiliation reference default system.
+ * @property {unknown[]} parents
+ * @property {unknown} [government] Null is explicit anarchy; absence is omission.
+ */
+/** @typedef {{contains?:HoldingsEntry[],governed_by?:HoldingsEntry[],governed_places?:HoldingsEntry[]}} Holdings */
+/** Historical shortcode projection for callers that explicitly need one.
+ * @param {unknown} value
+ * @returns {string[]}
  */
 export function shortcodesOf(value: unknown): string[];
-/**
- * Read a local note into a node, or `null` for a note that takes no part.
- *
- * @param {object} fm - The note's frontmatter.
- * @param {object} page - The page it publishes as.
- * @param {string} page.title - Its published title.
- * @param {string} page.url - Its URL.
- * @returns {HoldingsNode|null} The node, or `null` for a note that is neither
- *   a place nor an affiliation, or that declares no shortcode.
+/** Read local facts without converting government omission into anarchy.
+ * @param {object} fm
+ * @param {{title:string,url?:string,package?:string,system?:string,governmentSystem?:string}} page
+ * @returns {HoldingsNode|null}
  */
-export function holdingsNode(fm: object, { title, url }: {
+export function holdingsNode(fm: object, { title, url, package: pkg, system, governmentSystem }: {
     title: string;
-    url: string;
+    url?: string;
+    package?: string;
+    system?: string;
+    governmentSystem?: string;
 }): HoldingsNode | null;
-/**
- * Read a fetched index's places and affiliations as nodes.
- *
- * An entry carries what the producer's record stated — its name, `subType`,
- * `parents` and `domains` — and its page URL where the package publishes one.
- *
- * @param {Map<string, object>|undefined} foreignIndex - As
- *   {@link module:engine/metadata-index.loadForeignIndexes} returns it.
- * @returns {HoldingsNode[]} The nodes, in index order.
- */
+/** @param {Map<string,object>|undefined} foreignIndex @returns {HoldingsNode[]} */
 export function foreignHoldingsNodes(foreignIndex: Map<string, object> | undefined): HoldingsNode[];
-/**
- * Invert `parents` and `domains` into each page's lists.
- *
- * A shortcode is declared once per type: the first node declaring it wins,
- * so local nodes handed in ahead of fetched ones shadow a dependency's, the
- * way the link resolver answers. A node with no URL carries no lists of its
- * own, since there is no page to write them on — and is still an entry on
- * everybody else's, rendered as plain text. A name no node declares is
- * dropped: a `parents` naming nowhere is the map's finding, a `domains`
- * naming nowhere the reference check's.
- *
- * The result holds only pages with at least one entry on at least one list,
- * and a page's block carries only the keys it has entries for — the theme's
- * silent-disappear convention, kept at the source.
- *
- * @param {Iterable<HoldingsNode|null>} nodes - Every place and affiliation,
- *   local first. `parents` and `domains` are read as written, so a node
- *   built by hand may carry them as the note spells them.
- * @returns {Map<string, Holdings>} URL → the page's lists, sorted.
+/** Invert direct place facts. A stub remains a plain text entry; a stub's own
+ * absent page receives no lists. First declaration of a page Address wins;
+ * different document systems for one page normalize to its `note` identity.
+ * @param {Iterable<HoldingsNode|null>} nodes
+ * @param {object} [options]
+ * @param {Iterable<HoldingsNode|null>} [options.governmentNodes] Additional public
+ *   records without pages, participating only in government relationships.
+ * @returns {Map<string,Holdings>}
  */
-export function holdingsPages(nodes: Iterable<HoldingsNode | null>): Map<string, Holdings>;
+export function holdingsPages(nodes: Iterable<HoldingsNode | null>, { governmentNodes }?: {
+    governmentNodes?: Iterable<HoldingsNode | null> | undefined;
+}): Map<string, Holdings>;
 /**
- * Check a place note's tenure: a settlement, a site or a structure that no
- * affiliation's `domains` names is unheld land, reported as a warning at the
- * note's `type:` line.
- *
- * Declared on the `place` vocabulary as its type-level check, so the lint
- * runs it beside the field checks with the same index. Without an index the
- * question cannot be asked and nothing is reported.
+ * Advise when a place with an authored positive population omits government.
+ * Missing, null or zero population establishes no inhabited population.
+ * Property presence distinguishes omitted government from explicit null,
+ * which means complete anarchy. Non-null values are validated by the declared
+ * affiliation reference field. Neither geographic containment nor tenure
+ * supplies this fact, and the rule is independent of place subtype.
  *
- * @param {object} note - The note, as the link index hands it over.
- * @param {object} [opts]
- * @param {object} [opts.index] - The link index, holding every affiliation.
- * @returns {object[]} Findings.
+ * @param {object} note - The note with parsed frontmatter and raw source.
+ * @returns {object[]} Located warning findings.
  */
-export function checkHeld(note: object, { index }?: {
-    index?: object | undefined;
-}): object[];
+export function checkGovernment(note: object): object[];
 /**
- * The keys this module writes, and which a note cannot author: `contains`
- * and `held_by` on a place, `holdings` on an affiliation.
- *
+ * The historical API name for the government advisory. Tenure is no longer checked.
+ * @deprecated Use checkGovernment.
+ * @param {object} note - The place note.
+ * @param {object} [_opts] - Historical options, no longer needed.
+ * @returns {object[]} Government advisory findings.
+ */
+export function checkHeld(note: object, _opts?: object): object[];
+/** Derived keys, including retired keys removed from generated pages.
  * @type {readonly string[]}
  */
 export const HOLDINGS_KEYS: readonly string[];
-/**
- * The place subTypes tenure is checked on. A region is held through its
- * polity's `domains`, a world by nobody, a feature by nobody — a river has no
- * lord — so the rest are the kinds of place a body holds directly.
- *
+/** @deprecated Government advisories apply to every inhabited place subtype.
  * @type {readonly string[]}
  */
 export const HELD_SUBTYPES: readonly string[];
-/**
- * One entry of a holdings list — a page a reader is pointed at.
- */
 export type HoldingsEntry = {
-    /**
-     * The page's published title.
-     */
     title: string;
-    /**
-     * `<base><slug>/` — the page's address as every
-     *    href this build renders composes it. **Absent
-     *    for a stub**, which has no page: an entry with no
-     *    `url` renders as plain text.
-     */
-    url?: string | undefined;
-    /**
-     * The note's `type` — `place` or `affiliation`.
-     */
+    url?: string;
     type: string;
-    /**
-     * The note's `subType`, where it declares one.
-     */
-    subType?: string | undefined;
+    subType?: string;
 };
-/**
- * One place or affiliation, as the derivation reads it — a local page or a
- * fetched index entry through one shape.
- */
 export type HoldingsNode = {
-    /**
-     * Lower case.
-     */
     shortcode: string;
     type: "place" | "affiliation";
     subType?: string | undefined;
-    /**
-     * The page's published title.
-     */
     title: string;
-    /**
-     * The page's URL; absent where the package
-     *      publishes no page for it.
-     */
     url?: string | undefined;
     /**
-     * What a place sits within, as written.
+     * Owning content package.
      */
-    parents: string[];
+    package?: string | undefined;
     /**
-     * What an affiliation holds, as written.
+     * Own document system.
      */
-    domains: string[];
-};
-/**
- * The lists one page carries. Every key is optional, and a key present holds
- * at least one entry.
- */
-export type Holdings = {
+    system?: string | undefined;
     /**
-     * Places whose `parents` name this one.
+     * Full own Address.
      */
-    contains?: HoldingsEntry[] | undefined;
+    canonical?: string | undefined;
     /**
-     * Affiliations whose `domains` name this one.
+     * Affiliation reference default system.
      */
-    held_by?: HoldingsEntry[] | undefined;
+    governmentSystem?: string | undefined;
+    parents: unknown[];
     /**
-     * Places this affiliation's `domains` name.
+     * Null is explicit anarchy; absence is omission.
      */
-    holdings?: HoldingsEntry[] | undefined;
+    government?: unknown;
+};
+export type Holdings = {
+    contains?: HoldingsEntry[];
+    governed_by?: HoldingsEntry[];
+    governed_places?: HoldingsEntry[];
 };

package/types/engine/infobox.d.mts

@@ -27,6 +27,7 @@ export function isUnsetSentinel(value: unknown): boolean;
 /**
  * Whether a value is worth a row.
  *
+ * A field declaring `nullText` handles explicit null before this general test.
  * 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

package/types/engine/markdown-expressions.d.mts

@@ -9,7 +9,7 @@ export function sqlQueriesInMarkdown(body: any, fm?: {}): any[];
  *   {url: string|null, figures: Map<string, object>}|undefined,
  *   link?: Function}, file?: string, bodyLine?: number}} [options] -
  *   `figures` is the `ref` helper's own view of the corpus: `get` reads this
- *   note's `:::figure` fences by id, and `note` resolves another note's the
+ *   note's captioned items by id, and `note` resolves another note's the
  *   way a wikilink would — omitted, a cross-note address is refused rather
  *   than looked up. `link` overrides how a resolved reference renders; the
  *   default is a Markdown link to the target's own anchor.

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

@@ -133,6 +133,15 @@ export function dataFields(type: string, vocabulary?: Readonly<Record<string, Ty
  *   it has no `subType` at all — see {@link TypeVocabulary}.
  */
 export function subTypes(type: string, vocabulary?: Readonly<Record<string, TypeVocabulary>>): readonly string[] | null | undefined;
+/**
+ * Accepted migration input with no canonical field or emitted value.
+ *
+ * Legacy affiliation domains are ignored. They never supply a government.
+ * @param {string} type - The note type.
+ * @param {string} key - An authored data key.
+ * @returns {boolean} Whether the obsolete key is accepted during migration.
+ */
+export function isLegacyDataField(type: string, key: string): boolean;
 /**
  * One top-level frontmatter key.
  *
@@ -380,6 +389,10 @@ export type DataFieldSpec = {
      * - Allowed Address types, separate from `ref`.
      */
     accepts?: readonly string[] | undefined;
+    /**
+     * - Infobox text for an explicitly authored null with a declared meaning.
+     */
+    nullText?: string | undefined;
     /**
      * - Human-readable shape, for a finding and for
      * documentation.
@@ -464,8 +477,7 @@ export type TypeVocabulary = {
      * - A
      * check of the whole note, run by the frontmatter lint beside the field
      * checks with the same index. For a rule that is about the note rather than
-     * one of its fields — a place's tenure is a fact about every affiliation's
-     * `domains`, and is located at the note's `type:` line.
+     * one of its fields, located at the note's `type:` line.
      */
     check?: ((note: object, opts: {
         index?: object;

package/types/engine/populations.d.mts

@@ -16,7 +16,7 @@ export function foreignNode(canonical: string, entry: object): PopulationNode |
  * runs it with the index every reference check resolves through. Without an
  * index the questions cannot be asked and nothing is reported.
  *
- * Three rules, each reported on the note being linted: `over-held land` and
+ * Two geographical rules, each reported on the note being linted:
  * `over-full region` on the place whose figure is exceeded, and
  * `oversized settlement` on the settlement that exceeds one.
  *
@@ -35,8 +35,8 @@ export function checkPopulation(note: object, { index }?: {
  * restated figures drift. Each is located at the figure it wrote, counting
  * repeats so two rows carrying one number land on their own lines.
  *
- * A citation naming a note this package does not hold is skipped: a fetched
- * index carries no figure, so there is nothing to disagree with.
+ * A citation naming a note with no published population figure is skipped:
+ * there is nothing to disagree with.
  *
  * Declared as the `doc` vocabulary's type-level check.
  *
@@ -97,13 +97,9 @@ export type PopulationNode = {
      * superiors.
      */
     parents: string[];
-    /**
-     * What an affiliation holds.
-     */
-    domains: string[];
 };
 /**
- * The whole tree, indexed the three ways the rules read it.
+ * The whole tree, indexed by place, affiliation and geographical parent.
  */
 export type Corpus = {
     /**
@@ -119,11 +115,6 @@ export type Corpus = {
      * whose `parents` name it.
      */
     childrenOf: Map<string, string[]>;
-    /**
-     * Place shortcode → the polities
-     * whose `domains` name it.
-     */
-    holdersOf: Map<string, string[]>;
     /**
      * `type/shortcode` → the
      * node, for the citation rule.

package/types/engine/site-build.d.mts

@@ -182,7 +182,7 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * about every other page, known only once the whole tree has resolved — see
  * {@link module:engine/related-pages} — so an authored value is dropped the
  * way `aliases` is, and {@link renderPages} writes the derived block once it
- * holds the graph. `contains`, `held_by` and `holdings` are dropped for the
+ * holds the graph. Derived geographical and government lists are dropped for the
  * same reason — see {@link module:engine/holdings}. **So is `map`**: the
  * file a place page names is the one the build drew beside it — see
  * {@link module:engine/site-maps} — and a page with no drawing names none.
@@ -258,8 +258,8 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     secretErrors: {
         file: any;
         line: number;
-        column: number;
-        message: string;
+        column: any;
+        message: any;
     }[];
     captionErrors: {
         file: any;

package/types/engine/wikilinks.d.mts

@@ -18,7 +18,8 @@ export function anchorPageId(noteId: string, anchorSlug: string): string;
  *
  * @param {Array<{type: string, id: string, shortcode?: string|null,
  *   name?: string, pack?: string, docPack?: string, none?: boolean,
- *   draft?: boolean}>} docs -
+ *   draft?: boolean, anchors?: Set<string>, anchorUuids?: Record<string,string>,
+ *   docAnchorUuids?: Record<string,string>}>} docs -
  *   One entry per content note. `pack` / `docPack` name the packs the note's
  *   document and its documentation entry landed in; omitted, the conventional
  *   one-pack-per-type names stand in. `none` says the note declares
@@ -54,6 +55,9 @@ export function buildWikilinkIndex(docs: Array<{
     docPack?: string;
     none?: boolean;
     draft?: boolean;
+    anchors?: Set<string>;
+    anchorUuids?: Record<string, string>;
+    docAnchorUuids?: Record<string, string>;
 }>, packageId: string, foreign?: Map<string, object>, contentPackage?: string, { assets, noIndexPackages, referenceTargets, foreignReferences }?: {
     assets?: Map<string, object> | undefined;
     noIndexPackages?: Set<string> | undefined;