@heroiclands/package-build 22.21.0 → 22.23.0

package/engine/helpers.mjs

@@ -42,8 +42,15 @@ import footnotePlugin from "markdown-it-footnote";
 import deflistPlugin from "markdown-it-deflist";
 import { iconPlugin } from "./content-icons.mjs";
 import { imagePlugin, imagesIn } from "./content-images.mjs";
-import { resolveEmbeds } from "./content-embeds.mjs";
-import { foundryAddressProblem, pathnameProblem, resolvePathname } from "./pathnames.mjs";
+import { embedRole, resolveEmbeds } from "./content-embeds.mjs";
+import { collectAssetRecords } from "./asset-index.mjs";
+import { assetImageInfoByPathname } from "./art-fields.mjs";
+import {
+    assetPathnameKey,
+    foundryAddressProblem,
+    pathnameProblem,
+    resolvePathname,
+} from "./pathnames.mjs";
 import log from "loglevel";
 
 import { loadPackConfig } from "./pack-config.mjs";
@@ -65,9 +72,9 @@ import { linkFindingMessage } from "./wikilink-syntax.mjs";
 import { isDraftNote } from "./note-vocabulary.mjs";
 import { DERIVED_PACKED_TYPES, NEVER_PACKED_TYPES } from "./note-claims.mjs";
 import { expandContentTables } from "./content-tables.mjs";
-import { renderSecretBlocks } from "./content-secrets.mjs";
-import { renderAdmonitions } from "./content-admonitions.mjs";
-import { renderCaptionBlocks, scanCaptions } from "./content-captions.mjs";
+import { renderBlocks } from "./content-blocks.mjs";
+import { headingAttributesPlugin } from "./heading-attributes.mjs";
+import { renderFigureBlocks, scanFigures } from "./content-figures.mjs";
 import { positionInBody } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
 // registry can import them without reaching back through this one.
@@ -84,6 +91,9 @@ export {
     parseValueDesc,
 } from "./frontmatter.mjs";
 
+/** @type {Map<string, object>|undefined} */
+let localAssetImageInfoCache;
+
 /**
  * The markdown renderer every surface shares.
  *
@@ -95,6 +105,9 @@ export {
 export const md = markdownit({ html: true })
     .use(footnotePlugin)
     .use(deflistPlugin)
+    // A heading's attribute block, written onto the heading element rather than
+    // typeset into it — the reading the website's renderer does for itself.
+    .use(headingAttributesPlugin)
     .use(
         // Resolved per render, not at import: this constant is built before any
         // configuration is read, and a package's own icons live in the
@@ -114,25 +127,65 @@ export const md = markdownit({ html: true })
     // serves a file from inside the install, so a body image's address is
     // translated by the same rule `img:` follows.
     .use(
-        imagePlugin((src) => {
-            // **Reported upstream, never here.** A renderer has no channel to
-            // report through, and this one runs inside the very passes whose
-            // job is to collect findings — a throw would take the whole lint
-            // down and lose every other finding in the tree. So nothing reaches
-            // this point unreported: {@link convertNoteWikilinks} refuses a body
-            // image with no address inside the install before a compiler renders
-            // one, and the address passes report the same pathname with a line
-            // and a column. What is left here is a fallback for a caller with no
-            // configuration to resolve against, where the authored pathname is
-            // the most honest thing to emit.
-            try {
-                return resolveImg(src, loadPackConfig()) ?? src;
-            } catch {
-                return src;
-            }
-        }),
+        imagePlugin(
+            (src) => {
+                // **Reported upstream, never here.** A renderer has no channel to
+                // report through, and this one runs inside the very passes whose
+                // job is to collect findings — a throw would take the whole lint
+                // down and lose every other finding in the tree. So nothing reaches
+                // this point unreported: {@link convertNoteWikilinks} refuses a body
+                // image with no address inside the install before a compiler renders
+                // one, and the address passes report the same pathname with a line
+                // and a column. What is left here is a fallback for a caller with no
+                // configuration to resolve against, where the authored pathname is
+                // the most honest thing to emit.
+                try {
+                    return resolveImg(src, loadPackConfig()) ?? src;
+                } catch {
+                    return src;
+                }
+            },
+            (src) => {
+                // A body image is free to write the bare, own-package form,
+                // so the address is normalized to the pathname the cache
+                // below keys by before it is looked up.
+                try {
+                    const key = assetPathnameKey(src, loadPackConfig());
+                    return key ? localAssetImageInfo().get(key) : undefined;
+                } catch {
+                    return undefined;
+                }
+            },
+        ),
     );
 
+/**
+ * The pictures this package's own tree ships, by the pathname their address
+ * resolves to — read lazily and cached for the process, exactly as
+ * {@link loadPackConfig} is, since one compile reads one tree once.
+ *
+ * **Local only.** A picture embedded from a dependency carries no role or
+ * pixel size here: fetching a foreign package's own asset index to size one
+ * inline Foundry image is a cost this lazy cache does not pay, and the
+ * picture simply draws at the medium's ordinary size, as it always has.
+ *
+ * @returns {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ */
+function localAssetImageInfo() {
+    if (localAssetImageInfoCache) return localAssetImageInfoCache;
+    try {
+        const config = loadPackConfig();
+        const records = collectAssetRecords(config.paths.assets, {
+            contentPackage: config.contentPackage,
+            problems: [],
+        });
+        localAssetImageInfoCache = assetImageInfoByPathname(records);
+    } catch {
+        localAssetImageInfoCache = new Map();
+    }
+    return localAssetImageInfoCache;
+}
+
 md.renderer.rules.footnote_block_open = () =>
     '<section class="footnotes"><h2>Footnotes</h2><ol class="footnotes-list">\n';
 md.renderer.rules.footnote_caption = (tokens, idx, _options, env) => {
@@ -152,16 +205,26 @@ md.renderer.rules.footnote_open = (tokens, idx, options, env, renderer) => {
     return `<li id="fn${id}" class="footnote-item" value="${number}">`;
 };
 
-/** Render a note body with Foundry's secret section markup. */
-export function renderFoundryMarkdown(body, captions, footnoteNumbers, docId) {
-    const { markdown } = renderSecretBlocks(body, "foundry", (inner) => md.render(inner));
-    const admonitions = renderAdmonitions(markdown, (inner) => md.render(inner));
-    const captioned = renderCaptionBlocks(
-        admonitions.markdown,
-        (block) => md.render(block),
-        captions,
-    );
-    return md.render(captioned.markdown, { footnoteNumbers, docId });
+/**
+ * Render a note body with Foundry's named-block markup.
+ *
+ * @param {string} body - The body, tables expanded and wikilinks resolved.
+ * @param {Array<{id: string, label: string}>} [figures] - Labels assigned by
+ *   a note-wide scan, matched by id — see
+ *   {@link module:engine/content-figures.renderFigureBlocks}.
+ * @param {Map<string, number>} [footnoteNumbers] - Shared across the note.
+ * @param {string} [docId] - Threaded into footnote anchors.
+ * @param {(address: string) => string|undefined} [resolveRole] - From a
+ *   picture's address to the role its asset declares — see
+ *   {@link module:engine/content-figures.scanFigures}.
+ * @returns {string} The rendered HTML.
+ */
+export function renderFoundryMarkdown(body, figures, footnoteNumbers, docId, resolveRole) {
+    const blocks = renderBlocks(body, "foundry");
+    const figured = renderFigureBlocks(blocks.markdown, (block) => md.render(block), figures, {
+        resolveRole,
+    });
+    return md.render(figured.markdown, { footnoteNumbers, docId });
 }
 
 /**
@@ -547,11 +610,11 @@ export function makeFilename(name, id) {
  * the other.
  *
  * **`title` does not follow this rule**, and must not be made to. On a
- * `type: affiliation` note `title` is *also* a declared item field whose default
- * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
- * key the site emitter reads as the page title — so `title: null` stringifies
- * into the compiled document as the literal `"null"`. One key, two destinations
- * that disagree about what empty means.
+ * `type: affiliation` note `title` is a declared item field with its own
+ * default (`""`, in `sohl/item-fields.mjs`), authored only inside the item's
+ * own `sohl` block — the closed top-level vocabulary has no `title` entry, so
+ * there is no shared key for this function's null-versus-blank distinction to
+ * apply to.
  *
  * **`banner:` does not follow it either, deliberately.** It is not a file
  * inside a Foundry install: it reaches no compiled document and no book, its
@@ -943,7 +1006,9 @@ export function convertNoteWikilinks(
         docPack,
         index,
         captionLabels: new Map(
-            scanCaptions(source).captions.map((caption) => [caption.id, caption.label]),
+            scanFigures(source, { resolveRole: (address) => embedRole(index, address) })
+                .figures.filter((figure) => figure.id)
+                .map((figure) => [figure.id, figure.label]),
         ),
     });
     /**
@@ -1035,18 +1100,21 @@ export function convertNoteWikilinks(
 /* ------------------------------------------------------------------------ */
 
 /**
- * Expand prepared SQL tables before resolving wikilinks in generated cells.
+ * Expand prepared SQL tables and page lists before resolving wikilinks in the
+ * links they generate.
  * @param {string} body - The note body.
- * @param {object} ctx - Source and prepared query results.
+ * @param {object} ctx - Source and prepared results.
  * @param {string} ctx.name - Name used in diagnostics.
  * @param {number} [ctx.bodyLine] - The first body line in the source file.
  * @param {object[]} [ctx.sqlTables] - Prepared SQL results in document order.
+ * @param {object[]} [ctx.pageLists] - Prepared page lists in document order.
  * @returns {{markdown: string, lineMap: Array<{line: number, generated: boolean}>}}
  */
-export function expandNoteTables(body, { name, bodyLine, sqlTables }) {
+export function expandNoteTables(body, { name, bodyLine, sqlTables, pageLists }) {
     const { markdown, errors, lineMap } = expandContentTables(body ?? "", {
         source: name,
         sqlTables,
+        pageLists,
     });
     if (errors.length) {
         const err = new Error(errors.map((e) => `content table — ${e.reason}`).join("; "));

package/engine/homepage.mjs

@@ -131,12 +131,12 @@ export function isHomepage(fm) {
  * `name` and `shortcode` are permitted: the shortcode is what a link is
  * written with, and `name` titles the page like every other note's.
  *
- * **A named class, not an allow-list, and that boundary is the decision.** A
- * homepage's frontmatter is *emitted into the published page*
- * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
- * parameter this build has never heard of and has no standing to refuse.
- * Rejecting unknown keys would make every new theme parameter wait on a
- * package-build release.
+ * **A named class, not an allow-list, and that boundary is the decision.**
+ * What this class answers is a key the top-level vocabulary *accepts* and a
+ * homepage still cannot use, which is a different question from an unknown
+ * key: the frontmatter lint refuses those for every note alike, naming the
+ * closed vocabulary, so repeating that judgement per type would be a second
+ * answer to one question.
  *
  * `aliases` is deliberately not in the class: it is a **retired** field, refused
  * on every note whatever its type, so it is answered there rather than
@@ -340,7 +340,7 @@ function positionOfType(file) {
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
  * authored `name.full` wins, because a front page may greet a reader
- * differently from a package browser. A top-level `title` is also readable.
+ * differently from a package browser.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.
@@ -350,7 +350,7 @@ function positionOfType(file) {
  * @returns {string} The title.
  */
 export function homepageTitle(fm, config) {
-    const authored = fm?.name?.full ?? fm?.title;
+    const authored = fm?.name?.full;
     if (typeof authored === "string" && authored.trim()) return authored;
     const manifest = /** @type {Record<string, unknown>|undefined} */ (
         config?.packageBuild?.manifest

package/engine/index.mjs

@@ -220,6 +220,9 @@ export * as contentHtml from "./content-html.mjs";
 /** An image saying how wide it is and where it sits, in two closed vocabularies. */
 export * as contentImages from "./content-images.mjs";
 
+/** A list item opened with `[ ]` or `[x]`, which every surface reads as text. */
+export * as contentTaskLists from "./content-tasklists.mjs";
+
 /** `![[…]]` — the wikilink that renders a picture where it stands. */
 export * as contentEmbeds from "./content-embeds.mjs";
 

package/engine/infobox-registry.mjs

@@ -112,11 +112,13 @@ export function compilesSystemDocument(fm, map, router) {
  * @param {object} [options.router] - The pack router deciding which system
  *   compiles a document for this note. Defaults to the consuming repository's.
  * @param {object} [options.dates] - Calendar conversion context.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a note box's short-form Address resolves against.
  * @returns {object[]} The boxes, in the order every medium renders them.
  * @throws {Error} When the built set disagrees with what the note's type maps
  *   to — see {@link module:engine/infobox.assertInfoboxSet}.
  */
-export function noteInfoboxes(fm, { resolve, router = packRouter(), dates } = {}) {
+export function noteInfoboxes(fm, { resolve, router = packRouter(), dates, contentPackage } = {}) {
     const boxes = buildInfoboxes(fm, {
         maps: KNOWN_DOCUMENT_SUBTYPE_MAPS,
         providers: KNOWN_INFOBOXES,
@@ -124,6 +126,7 @@ export function noteInfoboxes(fm, { resolve, router = packRouter(), dates } = {}
         resolveField: resolveFieldValue,
         resolve,
         dates,
+        contentPackage,
     });
     return /** @type {object[]} */ (
         assertInfoboxSet(boxes, fm, { maps: KNOWN_DOCUMENT_SUBTYPE_MAPS })

package/engine/infobox-render.mjs

@@ -36,7 +36,7 @@
 
 import { encodeAddresses } from "./address-values.mjs";
 import { sectionHolds } from "./infobox.mjs";
-import { escapeTypst, escapeTypstString } from "./pdf-render.mjs";
+import { absolutePageUrl, escapeTypst, escapeTypstString } from "./pdf-render.mjs";
 
 /**
  * How many cells an attribute grid packs into a row.
@@ -226,16 +226,22 @@ export function sectionHasContent(section) {
  * 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.
  *
+ * A panel's rows address pages the same way prose does, so a page the book does
+ * not print is set as the absolute URL a reader can follow — see
+ * {@link module:engine/pdf-render.absolutePageUrl}.
+ *
  * @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.
+ * @param {string} [site] - The absolute address this book's pages are served at.
  * @returns {string} Typst markup.
  */
-export function linkToTypst(value, links, labelFor) {
+export function linkToTypst(value, links, labelFor, site) {
     const text = escapeTypst(value?.text ?? "");
     const anchor = value?.address ? links?.get(encodeAddresses(value.address)) : undefined;
     if (anchor) return `#link(<${labelFor(anchor)}>)[${text}]`;
-    if (value?.url) return `#link("${escapeTypstString(value.url)}")[${text}]`;
+    if (value?.url)
+        return `#link("${escapeTypstString(absolutePageUrl(value.url, site))}")[${text}]`;
     return text;
 }
 
@@ -375,7 +381,13 @@ export function infoboxTypstPreamble() {
             "fill: infobox-rule)[#upper(t)]; v(0.20em) }",
         '#let infobox-head(t) = { v(0.40em); text(size: 7.6pt, weight: "bold", ' +
             "tracking: 1.3pt, fill: infobox-rule)[#upper(t)]; v(0.16em) }",
+        // One definition-list style across the three surfaces: the term right
+        // against a fixed column so every term in the panel shares one edge,
+        // and space below the row rather than rows run together. A page has one
+        // width, so the stacked state the screen surfaces fall back to has
+        // nothing to answer here and is not drawn.
         "#let infobox-row(k, v) = grid(columns: (2.05cm, 1fr), column-gutter: 4pt, " +
+            "inset: (bottom: 2pt), align: (right + top, left + top), " +
             "text(size: 7pt, tracking: 0.5pt, fill: infobox-faint)[#upper(k)], text(size: 8pt)[#v])",
         "#let infobox-cell(lab, val) = align(center)[" +
             "#text(size: 7pt, tracking: 0.6pt, fill: infobox-faint)[#lab]#h(2.5pt)" +

package/engine/infobox.mjs

@@ -119,9 +119,20 @@ import { NOTE_VOCABULARY, dataFields } from "./note-vocabulary.mjs";
 import { readAliasedField } from "./retired-fields.mjs";
 import { subtypeRow } from "./document-subtypes.mjs";
 import { authoredKey } from "./system-block.mjs";
-import { formatDateInCalendar, formatNoteDate, parseNoteDate } from "./note-dates.mjs";
+import {
+    formatDateInCalendar,
+    formatNoteDate,
+    parseNoteDate,
+    resolvedDateFields,
+} from "./note-dates.mjs";
 import { displayBeingHeight, displayBeingWeight } from "./being-measurements.mjs";
-import { officeAnchor, officeRoster, readStandings, standingPhrase } from "./standings.mjs";
+import {
+    officeAnchor,
+    officeRoster,
+    rankAnchor,
+    readStandings,
+    standingPhrase,
+} from "./standings.mjs";
 
 /**
  * How a section arranges what it holds.
@@ -284,7 +295,7 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
     bgImage: Object.freeze({ withheld: "an image, which the box never carries" }),
     banner: Object.freeze({ withheld: "an image, which the box never carries" }),
     overlay: Object.freeze({ withheld: "an image, which the box never carries" }),
-    "lore.event": Object.freeze({ withheld: "chronology machinery, not a summary row" }),
+    "lore.events": Object.freeze({ withheld: "chronology machinery, not a summary row" }),
 
     assocSkill: Object.freeze({ label: "Skill" }),
     assocAffiliation: Object.freeze({ label: "Affiliation" }),
@@ -327,7 +338,8 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
     }),
     "being.appearance.complexion": Object.freeze({
         group: "appearance",
-        phrase: (v) => `${humanizeValue(v)} complexion`,
+        whole: true,
+        phrase: (v) => `${humanizedList(v)} complexion`,
     }),
     "being.appearance.extra_features": Object.freeze({ group: "appearance" }),
 });
@@ -469,6 +481,24 @@ export function humanizeValue(value) {
         .trim();
 }
 
+/**
+ * Several enumerated values as one clause — `weathered, ruddy and scarred`.
+ *
+ * A field that admits one value or a list of them reads as a single phrase, so
+ * the noun it qualifies is said once rather than once per value. Internal: the
+ * phrase that wants it is declared in this module.
+ *
+ * @param {unknown} value - One value, or a list of them.
+ * @returns {string} The text.
+ */
+function humanizedList(value) {
+    const parts = (Array.isArray(value) ? value : [value])
+        .filter((entry) => entry !== undefined && entry !== null && entry !== "")
+        .map((entry) => humanizeValue(entry));
+    if (parts.length < 2) return parts[0] ?? "";
+    return `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
+}
+
 /**
  * A value as a row shows it.
  *
@@ -633,16 +663,71 @@ function rosterRows(raw) {
     return rows;
 }
 
-/** Expand structured references using the existing linked-row shape. */
-function structuredRows(field, raw, resolve, label, fm) {
+/**
+ * A ladder of named ranks, one row each, ordered by the level a body confers.
+ *
+ * The **title is the label and its description is the value**, the same
+ * convention {@link rosterRows} draws a body's offices with, so a reader
+ * meets the two lists the same way. A rung's optional `lore` — already
+ * resolved to an Address by the time this runs — reads alongside the
+ * description rather than replacing it, since the description is what the
+ * rung itself states and the lore is a pointer to more.
+ *
+ * @param {unknown} raw - The authored `governance.ranks` list.
+ * @param {(ref: unknown, hint?: object) => object|undefined} resolve - The
+ *   medium's resolver.
+ * @returns {object[]|null} One row per rung, in ascending level, or `null`
+ *   where the value is not a list of them.
+ */
+function rankRows(raw, resolve) {
+    if (!Array.isArray(raw)) return null;
+    const rungs = raw
+        .filter((rung) => isMapping(rung) && hasValue(rung.title))
+        .toSorted((a, b) => Number(a.level ?? 0) - Number(b.level ?? 0));
+    const rows = [];
+    for (const rung of rungs) {
+        const anchor = rankAnchor(String(rung.title));
+        const description =
+            hasValue(rung.description) ? String(rung.description) : String(rung.title);
+        const lore = hasValue(rung.lore) ? linkValue(rung.lore, resolve, { type: "lore" }) : null;
+        rows.push({
+            ...(anchor ? { id: anchor } : {}),
+            label: String(rung.title),
+            kind: "text",
+            value: lore?.text ? `${description} (Lore: ${lore.text})` : description,
+        });
+    }
+    return rows;
+}
+
+/**
+ * Expand structured references using the existing linked-row shape.
+ *
+ * @param {string} [contentPackage] - This build's content package, the
+ *   default a short-form Address resolves against — the same value the site
+ *   build and the pack compiler read `contentPackage()` for. A row naming a
+ *   short Address with none handed to it skips rather than guesses.
+ */
+function structuredRows(field, raw, resolve, label, contentPackage) {
     if (field.standings) return standingRows(field, raw, resolve, label);
     if (field.roster) {
         const roster = rosterRows(raw);
         if (roster) return roster;
     }
-    if (Array.isArray(raw) && raw.some(isMapping)) {
-        const links = raw
-            .filter((entry) => isMapping(entry) && hasValue(entry.to))
+    if (field.ranks) {
+        const ranks = rankRows(raw, resolve);
+        if (ranks) return ranks;
+    }
+    // A relationship entry — `{to, ...}` — is a mapping that is not itself an
+    // 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.
+    const relations =
+        Array.isArray(raw) ? raw.filter((entry) => isMapping(entry) && !isAddressTuple(entry)) : [];
+    if (relations.length) {
+        const links = relations
+            .filter((entry) => hasValue(entry.to))
             .map((entry) => {
                 const link = linkValue(entry.to, resolve, { type: field.ref ?? "place" });
                 const details = Object.entries(entry)
@@ -666,7 +751,7 @@ function structuredRows(field, raw, resolve, label, fm) {
                 const address = parseAddress(
                     target,
                     {
-                        package: fm.package ?? "local",
+                        package: contentPackage,
                         system: "note",
                         types: new Set(field.accepts),
                     },
@@ -759,6 +844,8 @@ export function linkValue(ref, resolve, hint) {
  * @param {object} [options] - Options.
  * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
  *   reference to `{name, url?, uuid?, address?}`.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a relation row's short-form Address resolves against.
  * @param {object} [options.vocabulary] - The note vocabulary to read.
  * @param {object} [options.presentation] - The overlay to read.
  * @returns {object} The box.
@@ -784,12 +871,18 @@ export function noteInfobox(fm, options = {}) {
  */
 function noteBox(
     fm,
-    { resolve, dates, vocabulary = NOTE_VOCABULARY, presentation = NOTE_FIELD_PRESENTATION } = {},
+    {
+        resolve,
+        dates,
+        contentPackage,
+        vocabulary = NOTE_VOCABULARY,
+        presentation = NOTE_FIELD_PRESENTATION,
+    } = {},
 ) {
     const rows = [];
     /** @type {Set<string>} */
     const shown = new Set();
-    const name = fm?.name?.full ?? fm?.title;
+    const name = fm?.name?.full;
     if (hasValue(name)) rows.push({ label: "Name", kind: "text", value: String(name) });
     if (Array.isArray(fm?.name?.aliases) && fm.name.aliases.length) {
         rows.push({ label: "Aliases", kind: "list", value: fm.name.aliases });
@@ -843,7 +936,7 @@ function noteBox(
             raw,
             resolve,
             overlay.label ?? humanizeFieldName(field.name),
-            fm,
+            contentPackage,
         );
         if (structured) {
             rows.push(...structured);
@@ -857,7 +950,9 @@ function noteBox(
                 label: GROUP_LABELS[overlay.group] ?? humanizeFieldName(overlay.group),
                 entries: [],
             };
-            const parts = Array.isArray(raw) ? raw.filter(hasValue) : [raw];
+            // A `whole` phrase reads the value entire, so several values compose
+            // into one clause rather than repeating the noun once each.
+            const parts = overlay.whole || !Array.isArray(raw) ? [raw] : raw.filter(hasValue);
             for (const part of parts) {
                 group.entries.push(overlay.phrase ? overlay.phrase(part) : humanizeValue(part));
             }
@@ -879,6 +974,22 @@ function noteBox(
         shown.add(field.name);
     }
 
+    // `events` itself stays withheld — the family's shape is chronology
+    // machinery, not a summary row — but a reader meets each occurrence's
+    // own next date, the way a being's computed `age` reaches the box.
+    if (fm?.type === "lore" && Array.isArray(data.events) && data.events.length && dates) {
+        const resolved = resolvedDateFields(fm, dates);
+        for (const eventEntry of resolved.events ?? []) {
+            if (!eventEntry.next) continue;
+            rows.push({
+                label: "Next occurrence",
+                kind: "text",
+                value: eventEntry.next.prose ?? eventEntry.next.text,
+            });
+            shown.add("events");
+        }
+    }
+
     return {
         box: {
             id: NOTE_BOX_ID,
@@ -1061,6 +1172,8 @@ export function systemRowsSection(
  *   Resolves one declared field against the note.
  * @param {(ref: unknown) => object|undefined} [options.resolve] - Resolves a
  *   reference to `{name, url?, uuid?, address?}`.
+ * @param {string} [options.contentPackage] - This build's content package,
+ *   the default a note box's short-form Address resolves against.
  * @param {object} [options.vocabulary] - The note vocabulary to read.
  * @returns {object[]} The boxes.
  */
@@ -1071,11 +1184,12 @@ export function buildInfoboxes(fm, options) {
         compilesDocument,
         resolveField,
         resolve,
+        contentPackage,
         vocabulary = NOTE_VOCABULARY,
         dates,
     } = options;
 
-    const { box: note, shown: taken } = noteBox(fm, { resolve, vocabulary, dates });
+    const { box: note, shown: taken } = noteBox(fm, { resolve, vocabulary, dates, contentPackage });
     const boxes = [note];
 
     for (const map of maps ?? []) {

package/engine/itinerary-scenes.mjs

@@ -15,18 +15,10 @@ import { loadForeignIndexes } from "./metadata-index.mjs";
 import { authoredFrontmatter, isNoteRecord } from "./index-records.mjs";
 import { buildScene } from "./map-notes.mjs";
 import { buildJournalEntry } from "./journals.mjs";
+import { imageDimensions } from "./asset-types.mjs";
 import { makeId } from "./ids.mjs";
 import { stripAdventureKeys } from "./bundle-notes.mjs";
 
-/** The PNG's dimensions, from its fixed header. */
-function pngDimensions(file) {
-    const bytes = fs.readFileSync(file);
-    if (bytes.toString("hex", 0, 8) !== "89504e470d0a1a0a") {
-        throw new Error(`${file} is not a PNG`);
-    }
-    return [bytes.readUInt32BE(16), bytes.readUInt32BE(20)];
-}
-
 /** GraphViz's plain coordinates, converted to pixel positions on its PNG. */
 export function pinPositions(plain, width, height) {
     const graph = /^graph\s+\S+\s+(\S+)\s+(\S+)/m.exec(plain);
@@ -111,7 +103,9 @@ export function buildItineraryScenes({
         const plain = path.join(outDir, `from-${centre}.plain`);
         renderDot(dot, png, { engine: "neato", format: "png", nop: 2, dpi: 150 });
         renderDot(dot, plain, { engine: "neato", format: "plain", nop: 2 });
-        const [width, height] = pngDimensions(png);
+        const size = imageDimensions(png, ".png");
+        if (!size) throw new Error(`${png} carries no readable PNG size`);
+        const { width, height } = size;
         const positions = pinPositions(fs.readFileSync(plain, "utf8"), width, height);
         const sceneId = makeId("itinerary-scene", `${config.contentPackage}:${centre}`);
         const src = `${buildConfig.packageKind}/${buildConfig.packageId}/assets/maps/generated-itineraries/from-${centre}.png`;