@heroiclands/package-build 23.0.0 → 23.1.0

package/engine/journals.mjs

@@ -124,9 +124,15 @@ function namedBlockLines(markdown) {
  * calling that page "Introduction" would label the description as a preamble to
  * nothing.
  *
- * A figure fence carries its own record along onto the page it starts, as
- * `figure` — `null` for a page a heading started. {@link buildPages} reads it
- * to build the `image` or `text` page a fence begins; nothing else sets it.
+ * A captioned item's page holds the item alone, and carries the item's record
+ * as `figure` — `null` for every other page. {@link buildPages} reads it to
+ * build the `image` or `text` page; nothing else sets it. The page is named
+ * for the item's number, or else its caption's visible text.
+ *
+ * Body that follows an item, up to the next page opening, resumes in a
+ * **continuation** of the section the item interrupted: the section's name,
+ * level and classes, with `continues` naming the item it follows. A
+ * continuation holding nothing is not emitted.
  *
  * @param {string} body - Markdown body to split.
  * @param {string} [leadName] - Name of the page before the first heading.
@@ -135,8 +141,8 @@ function namedBlockLines(markdown) {
  *   name reads `Map 1` rather than `Figure 1` where it is due — see
  *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
- *   classes: string[], figure: object|null, markdown: string}>} Pages in
- *   document order.
+ *   classes: string[], figure: object|null, continues?: string,
+ *   markdown: string}>} Pages in document order.
  */
 export function splitPages(body, leadName = "Introduction", resolveRole) {
     const { markdown, definitions } = separateFootnotes(body);
@@ -150,16 +156,26 @@ export function splitPages(body, leadName = "Introduction", resolveRole) {
     const beforeFirstH1 = [];
     let current = null;
     let codeFence = null;
+    /** The page a heading last opened, which a captioned item interrupts. */
+    let section = { name: leadName, level: 1, classes: [] };
 
     const closeCurrent = () => {
         if (!current) return;
+        const markdown = current.lines.join("\n").trim();
+        // A continuation exists only to carry what follows its item; one
+        // holding nothing is not a page.
+        if (current.continues && !markdown) {
+            current = null;
+            return;
+        }
         pages.push({
             name: current.name,
             anchorSlug: current.anchorSlug,
             level: current.level,
             classes: current.classes,
             figure: current.figure ?? null,
-            markdown: current.lines.join("\n").trim(),
+            ...(current.continues ? { continues: current.continues } : {}),
+            markdown,
         });
         current = null;
     };
@@ -190,16 +206,32 @@ export function splitPages(body, leadName = "Introduction", resolveRole) {
         // lines it claims here are collected by `pageOpenings`, which also
         // skips a fence and a named block. A figure fence opens a page of its
         // own, named for the figure's label.
+        // A captioned item's page holds the item alone. The body after it
+        // resumes in a continuation of the section it interrupted, keyed on
+        // the item so its id holds still when pages move around it.
+        if (current?.figure && lineIndex > current.figure.close) {
+            const item = current.figure;
+            closeCurrent();
+            current = {
+                name: section.name,
+                anchorSlug: null,
+                level: section.level,
+                classes: section.classes,
+                continues: item.slug || item.label || captionPageName(item.caption),
+                lines: [],
+            };
+        }
+
         const opening = openings.get(lineIndex);
         const figure =
             !inCodeBlock && !blockLines.has(lineIndex) ? figureStarts.get(lineIndex) : null;
         if (figure) {
             closeCurrent();
             current = {
-                name: figure.label || figure.caption,
+                name: figure.label || captionPageName(figure.caption),
                 anchorSlug: figure.id || null,
                 level: 1,
-                classes: [],
+                classes: section.classes.includes(WITHHELD_CLASS) ? [WITHHELD_CLASS] : [],
                 figure,
                 lines: [line],
             };
@@ -214,6 +246,7 @@ export function splitPages(body, leadName = "Introduction", resolveRole) {
                 classes: opening.classes,
                 lines: [],
             };
+            section = current;
             continue;
         }
 
@@ -270,7 +303,18 @@ export function splitPages(body, leadName = "Introduction", resolveRole) {
 export function assertUniquePages(rawPages, noteName) {
     const anchors = new Set();
     const names = new Set();
+    const continuations = new Set();
     for (const page of rawPages) {
+        if (page.continues) {
+            const key = `${page.name}\u0000${page.continues}`;
+            if (continuations.has(key)) {
+                throw new Error(
+                    `note "${noteName}" has two captioned items both captioned "${page.continues}" in "${page.name}"; give one an {#anchor}`,
+                );
+            }
+            continuations.add(key);
+            continue;
+        }
         if (page.anchorSlug) {
             if (anchors.has(page.anchorSlug)) {
                 throw new Error(
@@ -321,16 +365,49 @@ export function assertUniqueAnchors(rawPages, noteName) {
  * a lint error. {@link assertUniquePages} states the same thing at compile
  * time, where the packer would otherwise report only an opaque duplicate key.
  *
+ * A continuation page shares its section's name, so it is keyed by that name
+ * and the captioned item it follows.
+ *
  * @param {string} entryId - The owning JournalEntry's `_id`.
- * @param {{anchorSlug: string|null, name: string}} page - From {@link splitPages}.
+ * @param {{anchorSlug: string|null, name: string, continues?: string}} page -
+ *   From {@link splitPages}.
  * @returns {string} A 16-character Foundry id.
  */
 export function journalPageId(entryId, page) {
-    return page.anchorSlug ?
-            anchorPageId(entryId, page.anchorSlug)
+    if (page.anchorSlug) return anchorPageId(entryId, page.anchorSlug);
+    return page.continues ?
+            makeId("journal-page", `${entryId}:${page.name}:after:${page.continues}`)
         :   makeId("journal-page", `${entryId}:${page.name}`);
 }
 
+/**
+ * The name of the page a caption begins: the caption's visible text.
+ *
+ * Foundry shows a page name as plain text, so a caption's markup — emphasis, a
+ * code span, a Markdown link, or the `@UUID[...]{label}` a resolved wikilink
+ * has already become, inside its wrapping `<span>` — reduces to the text a
+ * reader sees, the same text a reference to the caption displays. The markup
+ * itself stays in the page's content, where it renders.
+ *
+ * @param {string} caption - The figure's caption, as the journal pass sees it.
+ * @returns {string} Its visible text, whitespace collapsed.
+ */
+function captionPageName(caption) {
+    if (!caption) return "";
+    const [inline] = md.parseInline(caption, {});
+    const text = (inline?.children ?? [])
+        .map((token) =>
+            token.type === "text" || token.type === "code_inline" ? token.content
+            : token.type === "softbreak" || token.type === "hardbreak" ? " "
+            : "",
+        )
+        .join("");
+    return text
+        .replace(/@UUID\[[^\]]*\]\{([^}]*)\}/g, "$1")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+
 /**
  * Whether a caption carries markup an `image` page's `caption` field cannot
  * hold.
@@ -381,36 +458,13 @@ function soleFigurePicture(figure, page) {
     return IMAGE_EXTENSIONS.includes(extension) ? images[0].src : null;
 }
 
-/**
- * Whether a figure fence is the whole of the page {@link splitPages} gave it.
- *
- * A figure always starts a page of its own, but nothing closes one: trailing
- * prose before the next heading or figure stays on it, exactly as it would
- * behind an ordinary heading. An `image` page holds a `src` and a caption and
- * nowhere else to put that prose, so it is refused the type and kept a `text`
- * page, where the prose renders after the figure's own div as it always has.
- *
- * @param {object} figure - The figure record.
- * @param {object} page - From {@link splitPages}.
- * @returns {boolean} Whether nothing follows the fence's closing `:::`.
- */
-function figureIsWholePage(figure, page) {
-    const offset = figure.line - 1;
-    const after = page.markdown
-        .split("\n")
-        .slice(figure.close - offset + 1)
-        .join("\n");
-    return after.trim() === "";
-}
-
 /**
  * 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
- * picture, `image.caption` the caption text, the page named for the figure's
- * own number. Every other fence — grouped, an audio embed, a caption
- * `image.caption` cannot hold, or one trailing prose keeps company with —
+ * A captioned item holding exactly one picture, captioned with no inline
+ * markup, becomes a page of type `image`: `src` the picture, `image.caption`
+ * the caption text, the page named for the figure's own number. Every other
+ * item — grouped, an audio embed, or a caption `image.caption` cannot hold —
  * becomes a page of type `text`.
  *
  * The `text` page's content is rendered and then relabeled. The render sees
@@ -433,7 +487,7 @@ function figureIsWholePage(figure, page) {
  */
 function buildFigurePageFields(figure, page, pageId, footnoteNumbers, resolveRole) {
     const picture = soleFigurePicture(figure, page);
-    if (picture && figureIsWholePage(figure, page) && !captionCarriesMarkup(figure.caption)) {
+    if (picture && !captionCarriesMarkup(figure.caption)) {
         let src = picture;
         try {
             src = resolveImg(picture) ?? picture;
@@ -442,7 +496,7 @@ function buildFigurePageFields(figure, page, pageId, footnoteNumbers, resolveRol
             // image's own render takes when no configuration resolves it.
         }
         return {
-            name: figure.label || figure.caption,
+            name: figure.label || captionPageName(figure.caption),
             type: "image",
             src,
             image: figure.hasCaption ? { caption: figure.caption } : {},
@@ -460,7 +514,7 @@ function buildFigurePageFields(figure, page, pageId, footnoteNumbers, resolveRol
         resolveRole,
     );
     return {
-        name: figure.label || figure.caption,
+        name: figure.label || captionPageName(figure.caption),
         type: "text",
         text: {
             format: 1,
@@ -478,11 +532,12 @@ function buildFigurePageFields(figure, page, pageId, footnoteNumbers, resolveRol
  * @param {Array<object>} rawPages - From {@link splitPages}.
  * @param {string} entryId - The owning JournalEntry's `_id`.
  * @param {string} noteName - The note, for error messages.
- * A page whose heading carries `.secret` is given to the GM alone, by the one
- * ownership value Foundry reads as "nobody but a GM". Every other page states
- * no ownership and inherits the journal's. A figure-started page states none
- * either: {@link scanFigures} validates a figure's classes against its own
- * closed vocabulary, which carries no `.secret`.
+ * A page whose opening heading carries `.secret` is given to the GM alone, by
+ * the one ownership value Foundry reads as "nobody but a GM"; so is a captioned
+ * item's page and a continuation page inside such a section. Every other page
+ * states no ownership and inherits the journal's. A caption's own classes carry
+ * no `.secret`, because {@link scanFigures} validates them against a closed
+ * vocabulary without it.
  *
  * @param {Array<object>} figures - From {@link scanFigures}, numbered across
  *   the whole note. Read by a page a heading started; a page a figure started
@@ -536,7 +591,9 @@ export function buildPages(rawPages, entryId, noteName, figures, resolveRole) {
         return {
             _id: pageId,
             ...fields,
-            title: { show: true, level: page.level ?? 1 },
+            // A continuation resumes its section, whose title its first
+            // page already shows.
+            title: { show: !page.continues, level: page.level ?? 1 },
             ...(withheld ? { ownership: { default: WITHHELD_OWNERSHIP } } : {}),
             _key: `!journal.pages!${entryId}.${pageId}`,
         };

package/engine/literature-notes.mjs

@@ -93,7 +93,10 @@ export const LITERATURE_FIELDS = Object.freeze([
         shape: "list of Addresses",
         kind: "list",
         entryKind: "address",
-        describe: "The beings, places, gods, events and other notes the work concerns.",
+        anchors: Object.freeze(["event"]),
+        describe:
+            "The beings, places, gods and other notes the work concerns, and each " +
+            "event it concerns, named as `place-ironfells#sack`.",
     },
     {
         name: "language",

package/engine/literature-works.mjs

@@ -13,26 +13,25 @@
 
 /**
  * The works of literature that concern each page, derived from what the works
- * say. A `literature` lore note names its subjects in `data.subjects`; the site
- * build inverts that into a `works` list on every subject's page, so a reader on
- * a hero's, a place's or a god's page reaches the epics and legends about it.
- * The subject note writes nothing.
+ * say. A `literature` lore note names its subjects in `data.subjects`; the build
+ * inverts that into the **In song and story** section of every subject — see
+ * {@link module:engine/derived-sections} — so a reader of a hero, a place or a
+ * god reaches the epics and legends about it. The subject note writes nothing.
  *
- * A work in a fetched index lists on this package's subject pages when that
- * index carries its `subjects`. A subject in another package has no page here,
+ * A subject naming an event lists the work on the page of the note holding
+ * that event. A work in a fetched index lists on this package's subject pages
+ * when that index carries its `subjects`. A subject in another package has no page here,
  * so a local work naming one lists nowhere.
  *
  * @module
  */
 
-import { parseAddress, renderAddress } from "./address.mjs";
+import { parseAddress, renderAddress, splitAnchor } from "./address.mjs";
+import { AddressLink } from "./address-values.mjs";
 import { readCanonicalKey } from "./content-address.mjs";
 import { LITERATURE_SUBTYPE } from "./literature-notes.mjs";
 
-/** The page front-matter key the site build writes. */
-export const WORKS_KEY = "works";
-
-/** @typedef {{title: string, url?: string, form?: string}} WorkEntry */
+/** @typedef {{title: string, url?: string, address: string, form?: string}} WorkEntry */
 /**
  * @typedef {object} WorksNode
  * @property {string} key Own Address, normalized to the `note` system.
@@ -43,10 +42,18 @@ export const WORKS_KEY = "works";
  * @property {unknown[]} subjects A work's `data.subjects`; empty for any other note.
  */
 
-/** The note-system key of one Address, or "" where it names nothing. */
+/**
+ * The note-system key of one Address, or "" where it names nothing. A subject
+ * naming an event — `place-ironfells#sack`, or an {@link AddressLink} read
+ * from one — keys the note that holds the event.
+ */
 function addressKey(value, pkg, types) {
     if (value == null) return "";
-    const tuple = parseAddress(value, { package: pkg ?? "local", system: "note", types });
+    const note =
+        value instanceof AddressLink ? value.target
+        : typeof value === "string" ? splitAnchor(value).address
+        : value;
+    const tuple = parseAddress(note, { package: pkg ?? "local", system: "note", types });
     if (tuple.reason) return "";
     return renderAddress({ ...tuple, system: "note" }).toLowerCase();
 }
@@ -143,6 +150,7 @@ export function worksPages(nodes, { types }) {
             block.works.push({
                 title: work.title,
                 ...(work.url ? { url: work.url } : {}),
+                address: work.key,
                 ...(work.form ? { form: work.form } : {}),
             });
         }

package/engine/map-graphviz.mjs

@@ -4,7 +4,6 @@
 
 import fs from "node:fs";
 import { instance } from "@viz-js/viz";
-import { Resvg } from "@resvg/resvg-js";
 
 /** The layout engines accepted by the map command. */
 export const GRAPHVIZ_ENGINES = Object.freeze(["dot", "twopi", "neato"]);
@@ -12,22 +11,16 @@ export const GRAPHVIZ_ENGINES = Object.freeze(["dot", "twopi", "neato"]);
 const graphviz = await instance();
 
 /**
- * Render a DOT source file to SVG, plain positions, or a PNG background.
- *
- * A PNG uses the same Graphviz SVG layout as the vector map. SVG dimensions
- * are in points; resvg starts at 96 pixels per inch, so the zoom converts
- * the requested DPI to the same physical size as Graphviz's PNG output.
+ * Render a DOT source file to SVG.
  *
  * @param {string} dotPath - The saved DOT source.
  * @param {string} outPath - The output file.
  * @param {object} opts
  * @param {"dot"|"twopi"|"neato"} opts.engine - Layout engine.
- * @param {"svg"|"plain"|"png"} [opts.format="svg"] - Output format.
  * @param {2} [opts.nop] - Preserve positioned nodes as `neato -n2` does.
- * @param {number} [opts.dpi=96] - PNG resolution.
  * @returns {{warnings: string}} Renderer warnings.
  */
-export function renderDot(dotPath, outPath, { engine, format = "svg", nop, dpi = 96 }) {
+export function renderDot(dotPath, outPath, { engine, nop }) {
     if (!GRAPHVIZ_ENGINES.includes(engine)) {
         throw new Error(`Unsupported Graphviz engine "${engine}" for ${dotPath}`);
     }
@@ -35,19 +28,12 @@ export function renderDot(dotPath, outPath, { engine, format = "svg", nop, dpi =
     try {
         const result = graphviz.render(dot, {
             engine: nop === 2 ? "nop2" : engine,
-            format: format === "png" ? "svg" : format,
+            format: "svg",
         });
         if (result.status !== "success" || !result.output) {
             throw new Error(result.errors.map((error) => error.message).join("; ") || "no output");
         }
-        if (format === "png") {
-            const image = new Resvg(result.output, {
-                fitTo: { mode: "zoom", value: dpi / 96 },
-            }).render();
-            fs.writeFileSync(outPath, image.asPng());
-        } else {
-            fs.writeFileSync(outPath, result.output);
-        }
+        fs.writeFileSync(outPath, result.output);
         // The embedded renderer uses Times metrics for the generated bold
         // headings; its warning repeats for every map and needs no action.
         return {

package/engine/markdown-expressions.mjs

@@ -8,6 +8,7 @@ import { formatDateInCalendar, parseNoteDate } from "./note-dates.mjs";
 import { numberWords, numberDigits } from "./number-words.mjs";
 import { slugify } from "./content-slug.mjs";
 import { WIKILINK, authoredLabel, isSamePage, parseWikilink } from "./wikilink-syntax.mjs";
+import { EVENT_REFERENCE_FIELDS, eventFieldText } from "./event-fields.mjs";
 
 /**
  * An inline expression, as an author writes one.
@@ -152,7 +153,9 @@ const HELPERS = Object.freeze([
     }),
     Object.freeze({
         name: "ref",
-        params: 'address [form="number"|"full"|"title"]',
+        params:
+            'address [form="number"|"full"|"title"] ' +
+            '| address field="when"|"until"|"kind"|"summary"|"name"',
         summary:
             'A link to a captioned item, by its anchor — `"#thorn"` on this note, ' +
             '`"note-address#thorn"` on another. `form` is `number` (the default, and ' +
@@ -160,11 +163,21 @@ const HELPERS = Object.freeze([
             "caption; or `title`, the caption alone. Always renders as a link to the " +
             "figure, and a link inside the caption contributes only its label text. " +
             "The number rendered is the one the figure carries on the surface doing " +
-            "the rendering, whichever note names it.",
+            "the rendering, whichever note names it. With `field` in place of `form`, " +
+            'the address names an event — `"place-ironfells#sack"`, `"#sack"` on this ' +
+            'note, or `"lore-founding"` for a note holding one event — and the reference ' +
+            "prints that event's `when`, `until`, `kind`, `summary` or `name` as plain " +
+            "text, never a link; a date prints as the note format prints any date.",
         make:
-            ({ figures }) =>
+            ({ figures, events, fm, dates }) =>
             (address, options) => {
                 const hash = options?.hash ?? {};
+                if (Object.hasOwn(hash, "field")) {
+                    if (Object.hasOwn(hash, "form")) throw new RangeError(REF_BOTH_FAULT);
+                    const result = eventReference(address, hash.field, { events, fm, dates });
+                    if (result.problem) throw new RangeError(result.problem);
+                    return result.text;
+                }
                 const form = Object.hasOwn(hash, "form") ? hash.form : "number";
                 const formFault = refFormFault(form);
                 if (formFault) throw new RangeError(formFault);
@@ -184,6 +197,74 @@ const HELPERS = Object.freeze([
     }),
 ]);
 
+/** What a reference writing both `form` and `field` is told. */
+const REF_BOTH_FAULT = "ref takes form= for a figure or field= for an event, not both";
+
+/**
+ * The text one event reference prints, or why it prints nothing.
+ *
+ * The address is read through the wikilink grammar, as a figure reference's
+ * is: `"#sack"` names an event of this note, `"place-ironfells#sack"` one of
+ * another, and `"lore-founding"` a note holding exactly one event. The anchor
+ * must be one the note declares, and an `event` one.
+ *
+ * @param {unknown} address - The reference's address.
+ * @param {unknown} field - The field to print, one of {@link EVENT_REFERENCE_FIELDS}.
+ * @param {{events?: {note: (written: string) => object|undefined,
+ *   own?: (fm: object) => object|undefined}, fm?: object,
+ *   dates?: object}} context - Every note's events, this note's frontmatter,
+ *   and the reckoning context.
+ * @returns {{text: string}|{problem: string}} The text, with any link reduced to
+ *   its label, or the finding's message.
+ */
+function eventReference(address, field, { events, fm, dates } = {}) {
+    if (!EVENT_REFERENCE_FIELDS.includes(field))
+        return { problem: `ref's field must be one of ${EVENT_REFERENCE_FIELDS.join(", ")}` };
+    if (typeof address !== "string" || !address.trim())
+        return { problem: "ref needs an address naming an event" };
+    if (!events?.note)
+        return { problem: `ref "${address}" names an event, and this build resolves none` };
+    const parsed = parseWikilink(address);
+    const same = isSamePage(parsed);
+    const note = same ? events.own?.(fm) : events.note(parsed.target);
+    if (!note)
+        return {
+            problem:
+                same ?
+                    `ref "${address}" names an event of this note, which this build does not resolve`
+                :   `ref "${address}" addresses "${parsed.target}", which names no note this build resolves`,
+        };
+    let event;
+    if (parsed.anchor) {
+        const anchor = note.anchors.find((one) => one?.slug === parsed.anchor);
+        event = note.events.find((one) => one.id === parsed.anchor);
+        if (anchor && anchor.kind !== "event")
+            return {
+                problem:
+                    `ref "${address}" names "#${parsed.anchor}", a ${anchor.kind ?? "prose"} ` +
+                    "anchor — field= reads an event",
+            };
+        if (!event)
+            return {
+                problem: `ref "${address}" names no anchor "#${parsed.anchor}" in "${note.target}"`,
+            };
+    } else {
+        if (note.events.length !== 1)
+            return {
+                problem:
+                    note.events.length === 0 ?
+                        `ref "${address}" names "${note.target}", which holds no events`
+                    :   `ref "${address}" names "${note.target}", which holds ` +
+                        `${note.events.length} events — name one as "${parsed.target}#<id>"`,
+            };
+        event = note.events[0];
+    }
+    const value = eventFieldText(event, field, dates);
+    if (value.missing)
+        return { problem: `ref "${address}" field="${field}": that event states no ${field}` };
+    return { text: flattenCaptionLinks(value.text) };
+}
+
 /** The closed set of forms a figure reference may render as; `number` is the default. */
 const REF_FORMS = Object.freeze(["number", "full", "title"]);
 
@@ -382,10 +463,25 @@ export function sqlQueriesInMarkdown(body, fm = {}) {
  * @param {object} node - A `MustacheStatement`/`SubExpression` AST node.
  * @param {object} [figures] - This note's figures, and how to reach another
  *   note's — see {@link refFigure}.
+ * @param {object} [eventContext] - What an event reference reads — see
+ *   {@link eventReference}.
  * @returns {string|null} A finding message, or `null` when the call is sound.
  */
-function refCallFault(node, figures) {
+function refCallFault(node, figures, eventContext) {
     const pair = node.hash?.pairs?.find((entry) => entry.key === "form");
+    const fieldPair = node.hash?.pairs?.find((entry) => entry.key === "field");
+    if (fieldPair) {
+        if (fieldPair.value.type !== "StringLiteral")
+            return (
+                "ref's field must be a quoted string — one of " + EVENT_REFERENCE_FIELDS.join(", ")
+            );
+        if (pair) return REF_BOTH_FAULT;
+        const addressParam = node.params?.[0];
+        if (addressParam?.type !== "StringLiteral") return null;
+        return (
+            eventReference(addressParam.value, fieldPair.value.value, eventContext).problem ?? null
+        );
+    }
     if (pair && pair.value.type !== "StringLiteral")
         return `ref's form must be a quoted string — one of ${REF_FORMS.join(", ")}`;
     const form = pair ? pair.value.value : "number";
@@ -413,10 +509,12 @@ function refCallFault(node, figures) {
  * @param {string} body
  * @param {object} [figures] - This note's figures, and how to reach another
  *   note's — see {@link refFigure}.
+ * @param {object} [eventContext] - What an event reference reads — see
+ *   {@link eventReference}.
  * @returns {Array<{offset: number, message: string}>} One entry per faulty
  *   `{{...}}` expression, `offset` into `body`.
  */
-function refFaults(body, figures) {
+function refFaults(body, figures, eventContext) {
     const faults = [];
     for (const match of matchAllOutsideCode(body, EXPRESSION)) {
         let program;
@@ -428,7 +526,7 @@ function refFaults(body, figures) {
         const visit = (node) => {
             if (!node || typeof node !== "object") return;
             if (node.path?.original === "ref") {
-                const message = refCallFault(node, figures);
+                const message = refCallFault(node, figures, eventContext);
                 if (message) faults.push({ offset: match.index, message });
             }
             for (const parameter of node.params ?? []) visit(parameter);
@@ -452,22 +550,29 @@ function positionAt(body, offset, bodyLine) {
  *   figures?: {get: (id: string) => {label: string, caption: string,
  *   hasCaption: boolean}|undefined, note?: (address: string) =>
  *   {url: string|null, figures: Map<string, object>}|undefined,
- *   link?: Function}, file?: string, bodyLine?: number}} [options] -
+ *   link?: Function}, events?: {note: (written: string) => object|undefined,
+ *   own?: (fm: object) => object|undefined},
+ *   file?: string, bodyLine?: number}} [options] -
  *   `figures` is the `ref` helper's own view of the corpus: `get` reads this
  *   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.
+ *   default is a Markdown link to the target's own anchor. `events` is what an
+ *   event reference reads: every note's events by Address, from
+ *   {@link module:engine/event-fields.eventNoteIndex}; omitted, an event
+ *   reference is refused.
  */
 export function renderMarkdownExpressions(
     body,
-    { fm, dates, sqlResults, figures, file, bodyLine = 1 } = {},
+    { fm, dates, sqlResults, figures, events, file, bodyLine = 1 } = {},
 ) {
     const findings = [];
     const engine = Handlebars.create();
     for (const helper of HELPERS)
-        engine.registerHelper(helper.name, helper.make({ sqlResults, dates, figures }));
-    const staticFaults = new Map(refFaults(body, figures).map((f) => [f.offset, f.message]));
+        engine.registerHelper(helper.name, helper.make({ sqlResults, dates, figures, events, fm }));
+    const staticFaults = new Map(
+        refFaults(body, figures, { events, fm, dates }).map((f) => [f.offset, f.message]),
+    );
     const markdown = replaceOutsideCode(body, EXPRESSION, (source, _inside, offset) => {
         const fault = staticFaults.get(offset);
         if (fault) {

package/engine/metadata-index.mjs

@@ -307,6 +307,27 @@ function newestIndex(dirs) {
     return path.join(dir, entries[0]);
 }
 
+/**
+ * A published record's events, each with its `id`, the dates the publishing
+ * package resolved for it, and the entry as published, which an inline
+ * reference to one of its fields reads.
+ *
+ * @param {Record<string, any>} record - An index record.
+ * @returns {Array<{id?: string, when?: object, until?: object, entry: object}>|undefined}
+ *   In entry order, or `undefined` for a note with none.
+ */
+function publishedEvents(record) {
+    const events = record.data?.events;
+    if (!Array.isArray(events) || events.length === 0) return undefined;
+    const resolved = record.resolvedDates?.events ?? [];
+    return events.map((entry, position) => ({
+        ...(typeof entry?.id === "string" ? { id: entry.id } : {}),
+        ...(resolved[position]?.when ? { when: resolved[position].when } : {}),
+        ...(resolved[position]?.until ? { until: resolved[position].until } : {}),
+        entry,
+    }));
+}
+
 /**
  * Resolve every foreign address this build can cite, from the fetched indexes.
  *
@@ -437,6 +458,11 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 ...(Object.hasOwn(record.data ?? {}, "government") ?
                     { government: record.data.government }
                 :   {}),
+                // Every anchor the note declares, with its kind, and each of its
+                // events with its id and resolved date, so a consumer's
+                // `follows` edge into this package is resolved and ordered here.
+                noteAnchors: record.anchors ?? undefined,
+                events: publishedEvents(record),
                 // What a work of literature concerns and what kind of work it
                 // is, so a consumer's subject pages list a dependency's works.
                 ...(parts.type === "lore" && record.subType === "literature" ?