@heroiclands/package-build 22.25.0 → 22.27.0

package/engine/infobox.mjs

@@ -427,6 +427,7 @@ export function isUnsetSentinel(value) {
 /**
  * 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
@@ -722,7 +723,7 @@ function structuredRows(field, raw, resolve, label, contentPackage) {
     // Address: an authored plain list of addresses normalises to a list of
     // Address tuples, which `isMapping` also reports true for, and treating
     // one as a relationship keyed off a `to` it never carries is what emptied
-    // `lore`, `parents`, `domains` and `economy` silently.
+    // `lore`, `parents` and `economy` silently.
     const relations =
         Array.isArray(raw) ? raw.filter((entry) => isMapping(entry) && !isAddressTuple(entry)) : [];
     if (relations.length) {
@@ -943,6 +944,15 @@ function noteBox(
             if (structured.length) shown.add(field.name);
             continue;
         }
+        if (raw === null && field.nullText) {
+            rows.push({
+                label: overlay.label ?? humanizeFieldName(field.name),
+                kind: "text",
+                value: field.nullText,
+            });
+            shown.add(field.name);
+            continue;
+        }
         if (!hasValue(raw)) continue;
 
         if (overlay.group) {

package/engine/journals.mjs

@@ -196,7 +196,7 @@ export function splitPages(body, leadName = "Introduction", resolveRole) {
         if (figure) {
             closeCurrent();
             current = {
-                name: figure.label,
+                name: figure.label || figure.caption,
                 anchorSlug: figure.id || null,
                 level: 1,
                 classes: [],
@@ -404,7 +404,7 @@ function figureIsWholePage(figure, page) {
 }
 
 /**
- * The fields particular to the Foundry page a `:::figure` fence begins.
+ * The fields particular to the Foundry page a captioned item begins.
  *
  * A fence holding exactly one picture, captioned with no inline markup, and
  * standing alone on its page becomes a page of type `image`: `src` the
@@ -442,14 +442,16 @@ function buildFigurePageFields(figure, page, pageId, footnoteNumbers, resolveRol
             // image's own render takes when no configuration resolves it.
         }
         return {
-            name: figure.label,
+            name: figure.label || figure.caption,
             type: "image",
             src,
             image: figure.hasCaption ? { caption: figure.caption } : {},
         };
     }
     const label =
-        figure.hasCaption ? `${figure.label}: ${md.renderInline(figure.caption)}` : figure.label;
+        figure.hasCaption ?
+            `${figure.label ? `${figure.label}: ` : ""}${md.renderInline(figure.caption)}`
+        :   figure.label;
     const content = renderFoundryMarkdown(
         page.markdown,
         undefined,
@@ -458,7 +460,7 @@ function buildFigurePageFields(figure, page, pageId, footnoteNumbers, resolveRol
         resolveRole,
     );
     return {
-        name: figure.label,
+        name: figure.label || figure.caption,
         type: "text",
         text: {
             format: 1,
@@ -763,7 +765,7 @@ export class Journals extends BasePackCompiler {
 
         // The markdown this pass reads has already had its embeds rewritten
         // into ordinary images, each `src` the pathname `pathnameRoles` keys
-        // its roles by — so a `:::figure` of a map names itself `Map 1` here
+        // its roles by — so a captioned map names itself `Map 1` here
         // exactly as the website and the book name the same picture.
         const roles = pathnameRoles(this.linkIndex);
 

package/engine/markdown-expressions.mjs

@@ -154,7 +154,7 @@ const HELPERS = Object.freeze([
         name: "ref",
         params: 'address [form="number"|"full"|"title"]',
         summary:
-            'A link to a `:::figure` fence, by its anchor — `"#thorn"` on this note, ' +
+            'A link to a captioned item, by its anchor — `"#thorn"` on this note, ' +
             '`"note-address#thorn"` on another. `form` is `number` (the default, and ' +
             'admitted explicitly), rendering "Figure 13"; `full`, the number and the ' +
             "caption; or `title`, the caption alone. Always renders as a link to the " +
@@ -173,6 +173,10 @@ const HELPERS = Object.freeze([
                 const { parsed, figure, crossNote, noteFound, url } = refFigure(address, figures);
                 if (!figure)
                     throw new RangeError(refNotFoundFault(address, parsed, crossNote, noteFound));
+                if (form === "number" && !figure.label)
+                    throw new RangeError(
+                        'a reference to an unnumbered caption requires form="title" or form="full"',
+                    );
                 if (form !== "number" && !figure.hasCaption)
                     throw new RangeError(refNoCaptionFault(form, parsed));
                 return renderRef(figure, parsed, form, { url, link: figures?.link });
@@ -271,7 +275,7 @@ function flattenCaptionLinks(caption) {
 function refLabel(figure, form) {
     if (form === "number") return figure.label;
     const title = flattenCaptionLinks(figure.caption);
-    return form === "title" ? title : `${figure.label}: ${title}`;
+    return form === "title" || !figure.label ? title : `${figure.label}: ${title}`;
 }
 
 /**
@@ -394,6 +398,8 @@ function refCallFault(node, figures) {
     if (typeof address !== "string" || !address.trim()) return null;
     const { parsed, figure, crossNote, noteFound } = refFigure(address, figures);
     if (!figure) return refNotFoundFault(address, parsed, crossNote, noteFound);
+    if (form === "number" && !figure.label)
+        return 'a reference to an unnumbered caption requires form="title" or form="full"';
     if (form !== "number" && !figure.hasCaption) return refNoCaptionFault(form, parsed);
     return null;
 }
@@ -448,7 +454,7 @@ function positionAt(body, offset, bodyLine) {
  *   {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/engine/metadata-index.mjs

@@ -424,17 +424,19 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 // the record naming a path at all.
                 asset: record.asset ?? undefined,
                 // What a place is next to, reachable from and within, and
-                // what an affiliation holds, carried so a consumer's lint
+                // which affiliation governs it, carried so a consumer's lint
                 // checks a border across the package boundary from both ends,
                 // a consumer's map draws the dependency's places beside its
                 // own, and a consumer's pages list what a dependency's
-                // affiliation holds and what lies within its regions. A
+                // affiliation governs and what lies within its regions. A
                 // population lets the same checks include dependency figures.
                 borders: record.data?.borders ?? undefined,
                 routes: record.data?.routes ?? undefined,
                 parents: record.data?.parents ?? undefined,
-                domains: record.data?.domains ?? undefined,
                 population: record.data?.population ?? undefined,
+                ...(Object.hasOwn(record.data ?? {}, "government") ?
+                    { government: record.data.government }
+                :   {}),
                 package: pkg,
             });
             const entry = index.get(key);

package/engine/note-vocabulary.mjs

@@ -112,7 +112,7 @@ import { checkCultureChoice } from "./culture-choice.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
-import { checkHeld } from "./holdings.mjs";
+import { checkGovernment } from "./holdings.mjs";
 import {
     checkBeingMeasurement,
     parseBeingHeight,
@@ -153,6 +153,7 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
  *   so each takes a row labelled and anchored by the post's own name.
  * @property {"subType"} [keySelector] - An alternative `subType:<skill-subtype>` key.
  * @property {readonly string[]} [accepts] - Allowed Address types, separate from `ref`.
+ * @property {string} [nullText] - Infobox text for an explicitly authored null with a declared meaning.
  * @property {string} [shape] - Human-readable shape, for a finding and for
  *   documentation.
  * @property {string} [entryShape] - For a `scalar-or-map` field, what one
@@ -208,8 +209,7 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
  * @property {(note: object, opts: {index?: object}) => object[]} [check] - 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.
  */
 
 /* --------------------------------------------------------------------- */
@@ -512,8 +512,8 @@ const CHARGES = Object.freeze([
 /**
  * Everything `place` asks of a whole note.
  *
- * Two questions about one subject, and they are independent: who holds this
- * land, and — where the note is a body rather than somewhere within one — what
+ * Two questions about one subject, and they are independent: who governs this
+ * inhabited place, and — where the note is a body rather than somewhere within one — what
  * the body states about itself. A type declares one whole-note check, so the
  * two are composed here rather than either being folded into the other.
  *
@@ -522,7 +522,7 @@ const CHARGES = Object.freeze([
  * @returns {object[]} Findings from both.
  */
 function checkPlace(note, opts) {
-    return [...checkHeld(note, opts), ...checkWorldFacts(note, opts)];
+    return [...checkGovernment(note), ...checkWorldFacts(note, opts)];
 }
 
 /** Validate a being's authored date using the shared note-date grammar. */
@@ -1089,13 +1089,6 @@ export const NOTE_VOCABULARY = Object.freeze({
                 accepts: ["place"],
                 describe: "Where the affiliation's authority sits.",
             },
-            {
-                name: "domains",
-                ...LINKS,
-                ref: "place",
-                accepts: ["place"],
-                describe: "Places over which it holds sway.",
-            },
             { name: "population", ...NUM, describe: "How many people it counts." },
             {
                 name: "economy",
@@ -1563,6 +1556,18 @@ export const NOTE_VOCABULARY = Object.freeze({
                 check: checkPopulation,
                 describe: "Approximate population, to two significant digits.",
             },
+            {
+                name: "government",
+                ...LINK,
+                shape: "an Address or null",
+                ref: "affiliation",
+                accepts: ["affiliation"],
+                nullText: "Complete anarchy",
+                describe:
+                    "The governing affiliation Address; the default target type is affiliation. " +
+                    "Explicit null means complete anarchy. " +
+                    "A positive population with no government key produces an advisory.",
+            },
             {
                 name: "market",
                 ...NUM,
@@ -1856,3 +1861,15 @@ export function subTypes(type, vocabulary = NOTE_VOCABULARY) {
     if (!entry || !Object.hasOwn(entry, "subTypes")) return undefined;
     return entry.subTypes;
 }
+
+/**
+ * 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, key) {
+    return currentType(type) === "affiliation" && key === "domains";
+}

package/engine/pdf-build.mjs

@@ -745,7 +745,7 @@ export async function buildPdf({
      * @returns {string} Typst markup.
      */
     const figureCounts = { code: 0, table: 0, figure: 0, map: 0, poem: 0, prose: 0 };
-    // The role lookup a `:::figure` fence's `map` counter reaches through —
+    // The role lookup a captioned item's `map` counter reaches through —
     // see `engine/content-figures.mjs`'s `resolveRole`. Addressed form, for a
     // page's own scan below, which runs before its embeds are rewritten into
     // ordinary images; `pathRoles` is the same lookup keyed by the pathname

package/engine/pdf-render.mjs

@@ -85,10 +85,13 @@ export const BOOK_IMAGE_WIDTHS = Object.freeze({
     xlarge: "8cm",
     "full-width": '"full-width"',
 });
+import { markupAnchorFindings } from "./anchors.mjs";
 import { slugify } from "./content-slug.mjs";
+import { alertMarkdownPlugin, scanAlerts, ALERT_TYPES } from "./content-alerts.mjs";
+import { spanMarkdownPlugin, scanSpans } from "./content-spans.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { BLOCK_CONTAINERS, scanBlocks, BLOCK_NAMES } from "./content-blocks.mjs";
-import { inlineVerse, poetryStanzas } from "./content-poetry.mjs";
+import { inlineVerse, poetryStanzas, scanPoetry } from "./content-poetry.mjs";
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
 import { HTML_TAG, htmlMessage } from "./content-html.mjs";
 import { EXPRESSION } from "./markdown-expressions.mjs";
@@ -108,9 +111,7 @@ import {
  * a class and let CSS decide.
  */
 const BLOCK_PRINT = Object.freeze({
-    info: Object.freeze({ color: "#2f6f9f", background: "#eef6fb", symbol: "i" }),
     secret: Object.freeze({ color: "#5c4b8a", background: "#f2eefb", symbol: "!" }),
-    warn: Object.freeze({ color: "#9a6700", background: "#fff5db", symbol: "!" }),
 });
 
 import {
@@ -197,6 +198,24 @@ export function labelFor(anchor) {
 export function createParser(registry) {
     const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
     md.use(footnotePlugin);
+    md.use(alertMarkdownPlugin);
+    md.use(spanMarkdownPlugin);
+    // Verse is held inside a literal fence. Parse its inline content before
+    // footnote_tail collects definitions, using the surrounding note's env.
+    md.core.ruler.after("inline", "poetry_inline", (state) => {
+        for (const token of state.tokens) {
+            if (token.type !== "fence" || !/^poetry(?:\s|$)/.test(token.info?.trim() || ""))
+                continue;
+            token.meta ??= {};
+            token.meta.poetryStanzas = poetryStanzas(token.content).map((stanza) =>
+                stanza.map(({ text, level }) => {
+                    const children = [];
+                    state.md.inline.parse(inlineVerse(text), state.md, state.env, children);
+                    return { children, level };
+                }),
+            );
+        }
+    });
     md.use(deflistPlugin);
     md.use(iconPlugin(registry));
     // The same plugin the HTML surfaces use, so one directive is read once and
@@ -298,7 +317,7 @@ function offsetPosition(source, offset, opts = {}) {
  *   those passes did not run — `opts.prepared` — because each of them leaves the
  *   markup as written when it fails and has already said so in its own words.
  *
- * A `:::` block and a `:::figure` are the pair this pass does handle, and their
+ * A fenced div and a leading caption are the structures this pass handles, and their
  * own scanners decide what is well formed; their findings are reported here so
  * that a front-matter file, a prose file and a note body all get them.
  *
@@ -325,7 +344,7 @@ function reportUnrenderable(source, definitions, opts, original) {
     };
 
     const blocks = scanBlocks(source);
-    for (const error of blocks.errors)
+    for (const error of [...blocks.errors, ...scanAlerts(source).errors])
         report(linePosition(error.line, error.column, opts), "error", error.message);
     // A container's body, read for faults of its own — an empty box, an
     // attribute that does not parse — which the scan above passes over, because
@@ -349,6 +368,8 @@ function reportUnrenderable(source, definitions, opts, original) {
                 );
         }
     }
+    for (const error of [...scanSpans(source).errors, ...markupAnchorFindings(source)])
+        report(linePosition(error.line, error.column, opts), "error", error.message);
     for (const error of scanFigures(source).errors)
         report(linePosition(error.line, error.column, opts), "error", error.message);
     // An image sharing its paragraph with other text, or an address or title
@@ -527,14 +548,11 @@ export function markdownToTypst(markdown, opts = {}) {
         }
     }
     if (!opts.insideAdmonition) {
-        const figuresHoldingPoetry = scanFigures(source).figures;
+        const captionTargets = scanFigures(source).figures;
         const blocks = scanBlocks(source).blocks.filter(
             (block) =>
-                !figuresHoldingPoetry.some(
-                    (figure) =>
-                        block.name === "poetry" &&
-                        block.start >= figure.bodyStart &&
-                        block.end < figure.bodyEnd,
+                !captionTargets.some(
+                    (figure) => block.start >= figure.bodyStart && block.end < figure.bodyEnd,
                 ),
         );
         if (blocks.length) {
@@ -548,21 +566,13 @@ export function markdownToTypst(markdown, opts = {}) {
                         insideAdmonition: true,
                     }),
                 );
-                if (block.name === "poetry") {
-                    const content = poetryStanzas(block.body)
-                        .map((stanza) =>
-                            stanza
-                                .map(({ text, level }) => {
-                                    const verse = markdownToTypst(inlineVerse(text), {
-                                        ...sharedOptions,
-                                        insideAdmonition: true,
-                                    });
-                                    return `${level ? `#h(${level * 1.25}em)` : ""}${verse}`;
-                                })
-                                .join(" \\\n"),
-                        )
-                        .join("\n\n");
-                    output.push(`\n#block(width: 100%)[${content}]\n`);
+                if (block.name === "div") {
+                    const content = markdownToTypst(block.body, {
+                        ...sharedOptions,
+                        insideAdmonition: false,
+                    });
+                    const anchor = block.id ? ` <${sectionLabel(anchorPrefix, block.id)}>` : "";
+                    output.push(`\n#block(width: 100%)[${content}]${anchor}\n`);
                     cursor = block.end + 1;
                     continue;
                 }
@@ -629,7 +639,7 @@ export function markdownToTypst(markdown, opts = {}) {
                 { ...caption, imagesRemaining: { n: countImages(block) } }
             :   caption;
         const segments = [
-            caption.kind === "poem" ?
+            caption.kind !== "table" && caption.kind !== "figure" && caption.kind !== "map" ?
                 markdownToTypst(block, { ...sharedOptions, captions: undefined })
             :   renderMarkdownSegment(block, md, { ...ctx, caption: captioned }, definitions),
         ];
@@ -732,7 +742,23 @@ function renderBlock(tokens, i, out, ctx) {
         }
         case "fence":
         case "code_block": {
-            out.push(rawBlock(token.content, token.info?.trim() || ""));
+            if (token.type === "fence" && /^poetry(?:\s|$)/.test(token.info?.trim() || "")) {
+                const content = token.meta.poetryStanzas
+                    .map((stanza) =>
+                        stanza
+                            .map(({ children, level }) => {
+                                const verse = renderInline({ children }, ctx);
+                                return `${level ? `#h(${level * 1.25}em)` : ""}${verse}`;
+                            })
+                            .join(" \\\n"),
+                    )
+                    .join("\n\n");
+                const poem = scanPoetry(
+                    `${token.markup}${token.info}\n${token.content}${token.markup}`,
+                ).blocks[0];
+                const anchor = poem?.id ? ` <${sectionLabel(ctx.anchorPrefix, poem.id)}>` : "";
+                out.push(`\n#block(width: 100%)[${content}]${anchor}\n`);
+            } else out.push(rawBlock(token.content, token.info?.trim() || ""));
             return 1;
         }
         case "hr":
@@ -741,7 +767,20 @@ function renderBlock(tokens, i, out, ctx) {
         case "blockquote_open": {
             const end = matching(tokens, i, "blockquote_open", "blockquote_close");
             const inner = renderTokens(tokens.slice(i + 1, end), { ...ctx });
-            out.push(`\n#quote(block: true)[${inner}]\n\n`);
+            if (token.meta?.alert) {
+                const alert = token.meta.alert;
+                const colors = {
+                    note: "#0969da",
+                    tip: "#1a7f37",
+                    important: "#8250df",
+                    warning: "#9a6700",
+                };
+                const spec = ALERT_TYPES[alert.type];
+                const icon = `#image(bytes("${escapeTypstString(spec.svg.replace("<svg ", '<svg xmlns="http://www.w3.org/2000/svg" ').replaceAll("currentColor", colors[alert.type]))}"), format: "svg", width: 0.9em, height: 0.9em)`;
+                const anchor = alert.id ? ` <${sectionLabel(ctx.anchorPrefix, alert.id)}>` : "";
+                const box = `\n#block(width: 100%, stroke: (left: 2pt + rgb("${colors[alert.type]}")), inset: 8pt, above: 0.7em, below: 0.7em)[#text(fill: rgb("${colors[alert.type]}"), weight: "bold")[${icon} ${inlineMarkup(alert.title ?? alert.attributes?.title ?? spec.title, ctx)}]\n\n${inner}]${anchor}\n\n`;
+                out.push(alert.classes?.includes("border") ? figureBorder(box) : box);
+            } else out.push(`\n#quote(block: true)[${inner}]\n\n`);
             return end - i + 1;
         }
         case "bullet_list_open":
@@ -964,13 +1003,15 @@ function inlineMarkup(text, ctx) {
  */
 function captionMarkup(caption, ctx) {
     const label = escapeTypst(caption.label);
-    return caption.hasCaption ? `${label}: ${inlineMarkup(caption.caption, ctx)}` : label;
+    return caption.hasCaption ?
+            `${label ? `${label}: ` : ""}${inlineMarkup(caption.caption, ctx)}`
+        :   label;
 }
 
 /**
  * How many markdown images a figure's contents carry.
  *
- * A grouped figure's `///` caption describes the whole plate, not any one
+ * A grouped figure's leading caption describes the whole plate, not any one
  * picture in it, so {@link renderImage} needs to know which image is the
  * last — the one that carries the group's single label and anchor — and this
  * is the count it counts down from.
@@ -1157,6 +1198,24 @@ function renderInline(token, ctx) {
             case "code_inline":
                 out.push(inlineRaw(child.content));
                 break;
+            case "span_open": {
+                out.push("#box[");
+                break;
+            }
+            case "span_close": {
+                let depth = 1;
+                let opening;
+                for (let j = i - 1; j >= 0; j -= 1) {
+                    if (children[j].type === "span_close") depth += 1;
+                    if (children[j].type === "span_open" && --depth === 0) {
+                        opening = children[j];
+                        break;
+                    }
+                }
+                const id = opening?.attrGet?.("id");
+                out.push(`]${id ? ` <${sectionLabel(ctx.anchorPrefix, id)}>` : ""}`);
+                break;
+            }
             case "strong_open":
                 out.push("#strong[");
                 break;