@heroiclands/package-build 25.5.4 → 25.5.5

package/engine/content-verse.mjs

@@ -140,7 +140,7 @@ export function scanVerse(source, { checkWorks = true } = {}) {
         for (const message of [...region.problems, ...refusedAttributes(region.attributes)])
             errors.push({ ...at, message });
         if (!region.closed) errors.push({ ...at, message: "verse div needs a closing ::: line" });
-        if (!region.body.trim()) errors.push({ ...at, message: "verse div is empty" });
+        if (!region.logicalBody.trim()) errors.push({ ...at, message: "verse div is empty" });
         for (const key of Object.keys(region.attributes))
             if (!VERSE_KEYS.includes(key))
                 errors.push({
@@ -150,7 +150,10 @@ export function scanVerse(source, { checkWorks = true } = {}) {
                 });
         if (region.attributes.work !== undefined && !region.attributes.work.trim())
             errors.push({ ...at, message: "work= needs a nonempty page-local key" });
-        const model = parseVerse(region.body, { footnotes: definedFootnotes });
+        const model = parseVerse(region.logicalBody, {
+            footnotes: definedFootnotes,
+            sourceOffsets: region.bodyOffsets,
+        });
         for (const finding of model.errors) {
             const preceding = text.slice(0, region.bodyStart + finding.offset);
             errors.push({
@@ -254,6 +257,8 @@ function keyColumn(opening, key) {
  * @property {string[]} classes - Authored presentation classes.
  * @property {string} indent - Opening div's leading spaces.
  * @property {string} body - Authored verse body.
+ * @property {string} logicalBody - Body without Markdown container prefixes.
+ * @property {number[]} bodyOffsets - Logical UTF-16 offsets mapped to authored body offsets, including the end.
  * @property {VerseModel} model - Logical structure relative to the body.
  */
 
@@ -291,10 +296,10 @@ function cantoLine(line) {
  * Offsets are UTF-16 positions relative to body. Delimiters and indentation are
  * layout ranges; source newlines inside a logical line contribute one space.
  * @param {string} body - Authored verse body.
- * @param {{inline?: boolean, footnotes?: ReadonlySet<string>}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels.
+ * @param {{inline?: boolean, footnotes?: ReadonlySet<string>, sourceOffsets?: number[]}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels; sourceOffsets maps projected body positions to authored offsets, including the end.
  * @returns {VerseModel} The shared structure with offsets relative to the body.
  */
-export function parseVerse(body, { inline = false, footnotes = new Set() } = {}) {
+export function parseVerse(body, { inline = false, footnotes = new Set(), sourceOffsets } = {}) {
     const source = String(body ?? "");
     const groups = [],
         boundaries = [],
@@ -594,6 +599,35 @@ export function parseVerse(body, { inline = false, footnotes = new Set() } = {})
     for (const group of groups)
         if (!group.cantoBreak)
             group.label = multi ? `${group.canto}:${group.stanza}` : String(group.stanza);
+    if (sourceOffsets) {
+        const position = (offset) => sourceOffsets[offset];
+        const bounds = (item) => {
+            item.from = position(item.from);
+            item.to = position(item.to);
+        };
+        for (const line of new Set([
+            ...cantos.flatMap((canto) => canto.stanzas.flatMap((stanza) => stanza.lines)),
+            ...pendingNotes,
+        ])) {
+            bounds(line);
+            line.offsets = line.offsets.map(position);
+        }
+        for (const canto of cantos) for (const stanza of canto.stanzas) bounds(stanza);
+        for (const group of groups) bounds(group);
+        for (const boundary of boundaries) boundary.sourceOffset = position(boundary.sourceOffset);
+        for (const range of layout) {
+            range[0] = position(range[0]);
+            range[1] = position(range[1]);
+        }
+        for (const finding of errors) finding.offset = position(finding.offset);
+        // Container bytes remain layout in projections that read the authored body.
+        let previous = 0;
+        for (const offset of sourceOffsets) {
+            if (offset > previous) layout.push([previous, offset]);
+            previous = offset + 1;
+        }
+        layout.sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+    }
     return { cantos, groups, boundaries, layout, errors, notes: pendingNotes };
 }
 
@@ -816,16 +850,24 @@ export function renderVerse(source, { verses = new Map() } = {}) {
             !lines.slice(0, block.start).some((line) => /^ *(?:[-+*]|\d+[.)]) +/.test(line))
         )
             indent = "";
+        const openingPrefix = lines[block.start].slice(0, block.column - 1);
+        // A list marker belongs only to the opening line; its continuation is spaces.
+        const prefix = openingPrefix.replace(/(?:[-+*]|\d+[.)])[ \t]+/g, (mark) =>
+            " ".repeat(mark.length),
+        );
+        const container = prefix.includes(">") || openingPrefix !== prefix;
+        const continuation = container ? prefix : indent;
+        const blank = continuation.trimEnd();
         output.push(
             "",
-            `${indent}<div ${attrs.join(" ")}>`,
-            "",
+            `${container ? openingPrefix : indent}<div ${attrs.join(" ")}>`,
+            blank,
             ...verseMarkdown(block.body, { labelled, model, presentation: transported })
                 .split("\n")
-                .map((line) => (line ? indent + line : line)),
-            "",
-            `${indent}</div>`,
-            "",
+                .map((line) => (line ? continuation + line : blank)),
+            blank,
+            `${continuation}</div>`,
+            blank,
         );
         cursor = block.end + 1;
     }

package/engine/core-report.mjs

@@ -79,7 +79,7 @@ function idsOf(word) {
  * @param {Iterable<Record<string, any>>} records - Index records.
  * @param {{language?: string}} [options] - A language to report alone, by its
  *   name, shortcode or reference slug whether or not it states `data.core`.
- * @returns {{concepts: number, languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
+ * @returns {{concepts: number, notCovered: string[], languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
  *   The report, or the problem when there is no concept list or the language
  *   asked for is none.
  */
@@ -113,6 +113,13 @@ export function coreReport(records, { language } = {}) {
     const groups = [...new Set(concepts.map((concept) => concept.group))];
     return {
         concepts: concepts.length,
+        notCovered:
+            language === undefined ?
+                languages
+                    .filter((record) => record.data?.core !== true)
+                    .map(nameOf)
+                    .sort((a, b) => a.localeCompare(b))
+            :   [],
         languages: chosen.map((record) => {
             const have = new Set();
             const forms = new Set();
@@ -154,24 +161,26 @@ export function coreReport(records, { language } = {}) {
  * A core report as text: one block per language, its missing concepts under
  * their groups with counts, each concept's id and gloss tab-separated.
  *
- * @param {{concepts: number, languages: Array<object>}} report - A report from {@link coreReport}.
+ * The default report ends with the names of languages it does not measure.
+ *
+ * @param {{concepts: number, notCovered: string[], languages: Array<object>}} report - A report from {@link coreReport}.
  * @returns {string} The text, ending in a newline.
  */
 export function coreReportText(report) {
-    if (!report.languages.length) return "No language states `data.core: true`.\n";
-    return report.languages
-        .map((one) => {
-            if (!one.missing.length)
-                return `${one.name} (${one.language}): all ${one.total} core concepts have a word\n`;
-            const lines = [
-                `${one.name} (${one.language}): ${one.total - one.covered} of ${one.total} core concepts have no word`,
-            ];
-            for (const group of one.missing) {
-                lines.push(`  ${group.group}: ${group.count} of ${group.total}`);
-                for (const concept of group.concepts)
-                    lines.push(`    ${concept.id}\t${concept.gloss}`);
-            }
-            return `${lines.join("\n")}\n`;
-        })
-        .join("\n");
+    const blocks = report.languages.map((one) => {
+        if (!one.missing.length)
+            return `${one.name} (${one.language}): all ${one.total} core concepts have a word\n`;
+        const lines = [
+            `${one.name} (${one.language}): ${one.total - one.covered} of ${one.total} core concepts have no word`,
+        ];
+        for (const group of one.missing) {
+            lines.push(`  ${group.group}: ${group.count} of ${group.total}`);
+            for (const concept of group.concepts) lines.push(`    ${concept.id}\t${concept.gloss}`);
+        }
+        return `${lines.join("\n")}\n`;
+    });
+    if (!blocks.length) blocks.push("No language states `data.core: true`.\n");
+    if (report.notCovered.length)
+        blocks.push(`Not covered (no data.core): ${report.notCovered.join(", ")}\n`);
+    return blocks.join("\n");
 }

package/engine/language-names.mjs

@@ -29,11 +29,11 @@
  *   tongue whose forms differ by gender states a map of gender words to a
  *   pattern or a list of them. A gender with no pattern of its own takes every
  *   pattern stated.
- * - `given` — given names, one list per gender word of the closed gender
- *   vocabulary. `female` and `male` are required. `{given}` draws from the
- *   person's gender's list, or from every given list together where that gender
- *   has none; `{given.<gender>}` draws from that gender's list whatever the
- *   person's gender, as a patronymic draws a father's name.
+ * - `given` — one list of names for everyone, or a map of gender words to
+ *   lists. The map requires `female` and `male`. `{given}` draws from the shared
+ *   list, the person's gender's list, or every given list together where that
+ *   gender has none. `{given.<gender>}` draws from the shared list or that
+ *   gender's list whatever the person's gender, as a patronymic draws a father's name.
  * - `en` — English names, in groups of lists: `en.epithet` is a list a pattern
  *   draws from as `{en.epithet}`, as `"{given} the {en.epithet}"` does. English
  *   names are never encoded in the tongue's script or checked against its
@@ -73,7 +73,7 @@ const LIST_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
 const PLACEHOLDER = /^([A-Za-z][A-Za-z0-9_]*)(?:\.([A-Za-z][A-Za-z0-9_]*))?$/;
 
 /**
- * The genders every `data.names.given` states a list for.
+ * The genders a mapped `data.names.given` states a list for.
  *
  * A function rather than a `const`: `note-vocabulary.mjs` reads it while the
  * module graph is still evaluating.
@@ -317,8 +317,12 @@ export function namesProblems(names, lookVocabulary) {
 
     const given = names[GIVEN_LIST];
     if (given === undefined || given === null) shape([], "`data.names` must state `given`", true);
+    else if (Array.isArray(given)) checkList([GIVEN_LIST]);
     else if (!isPlainMap(given))
-        shape([GIVEN_LIST], `\`${label([GIVEN_LIST])}\` should be a map of genders to lists`);
+        shape(
+            [GIVEN_LIST],
+            `\`${label([GIVEN_LIST])}\` should be a list of names or a map of genders to lists`,
+        );
     else {
         const genders = genderWords(lookVocabulary);
         for (const gender of requiredGivenGenders()) {
@@ -428,7 +432,18 @@ export function namesProblems(names, lookVocabulary) {
             }
             named.add(part.list);
             if (part.gender !== undefined) {
-                if (givenMap[part.gender] === undefined || givenMap[part.gender] === null)
+                if (Array.isArray(given)) {
+                    if (!genders.includes(part.gender)) {
+                        const guess = nearest(part.gender, genders);
+                        problem(
+                            path,
+                            `${JSON.stringify(part.gender)} is not a gender; ` +
+                                `\`{${placeholderText(part)}}\` in \`${label(path)}\` takes ` +
+                                genders.join(", ") +
+                                (guess ? `. Did you mean "${guess}"?` : ""),
+                        );
+                    }
+                } else if (givenMap[part.gender] === undefined || givenMap[part.gender] === null)
                     problem(
                         path,
                         `\`{${placeholderText(part)}}\` in \`${label(path)}\` names no list: ` +
@@ -476,7 +491,7 @@ export function namesProblems(names, lookVocabulary) {
  * keys cannot: a pattern that does not parse, a placeholder naming no list, a
  * list no pattern names, a list name a placeholder cannot spell, an empty list
  * of patterns or of names, an empty name, a pattern or given list keyed by no
- * gender, and a missing `female` or `male` list. Each is located at the pattern, list, entry or key at fault.
+ * gender, and a missing `female` or `male` list in a gender map. Each is located at the pattern, list, entry or key at fault.
  *
  * @param {object} note - The note: `file`, `raw` and parsed `fm`.
  * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
@@ -534,8 +549,8 @@ export function namesFindings(note, lookVocabulary) {
 }
 
 /**
- * The given names a gender draws from: its own list, or every given list
- * together where it has none.
+ * The given names a gender draws from: the shared list, its own list, or
+ * every given list together where it has none.
  *
  * @param {object} names - Checked `data.names`.
  * @param {string} gender - A gender word.
@@ -543,6 +558,7 @@ export function namesFindings(note, lookVocabulary) {
  */
 export function givenNames(names, gender) {
     const given = names[GIVEN_LIST];
+    if (Array.isArray(given)) return given;
     if (Array.isArray(given[gender])) return given[gender];
     return [...new Set(Object.values(given).filter(Array.isArray).flat())];
 }
@@ -551,29 +567,42 @@ export function givenNames(names, gender) {
 function listFor(names, part, gender) {
     if (part.sub !== undefined) return names[part.list][part.sub];
     if (part.list !== GIVEN_LIST) return names[part.list];
-    if (part.gender !== undefined) return names[GIVEN_LIST][part.gender];
+    if (part.gender !== undefined) return givenNames(names, part.gender);
     return givenNames(names, gender);
 }
 
 /**
- * A name drawn from a language's lists: one of the gender's patterns, where it
- * has more than one, then each placeholder an even draw from its list.
+ * A name's selected literal and placeholder parts. One of the gender's
+ * patterns is selected first, then each placeholder is an even draw from its
+ * source list.
  *
  * @param {object} names - Checked `data.names`.
  * @param {string} gender - A gender word.
  * @param {() => number} next - A stream of numbers in `[0, 1)`.
- * @returns {string} The name.
+ * @returns {(PatternPart & {text: string})[]} The selected parts in pattern order.
  */
-export function drawName(names, gender, next) {
+export function drawNameParts(names, gender, next) {
     const patterns = patternsFor(names, gender);
     const pattern =
         patterns.length > 1 ? patterns[Math.floor(next() * patterns.length)] : patterns[0];
-    return parsePattern(pattern)
-        .parts.map((part) => {
-            if ("literal" in part) return part.literal;
-            const list = listFor(names, part, gender);
-            return list[Math.floor(next() * list.length)];
-        })
+    return parsePattern(pattern).parts.map((part) => {
+        if ("literal" in part) return { ...part, text: part.literal };
+        const list = listFor(names, part, gender);
+        return { ...part, text: list[Math.floor(next() * list.length)] };
+    });
+}
+
+/**
+ * A name drawn from a language's lists.
+ *
+ * @param {object} names - Checked `data.names`.
+ * @param {string} gender - A gender word.
+ * @param {() => number} next - A stream of numbers in `[0, 1)`.
+ * @returns {string} The name.
+ */
+export function drawName(names, gender, next) {
+    return drawNameParts(names, gender, next)
+        .map((part) => part.text)
         .join("");
 }
 
@@ -640,7 +669,8 @@ export function nameMisfit(full, names, gender) {
     const text = nfc(full);
     const given = names[GIVEN_LIST];
     const own = givenNames(names, gender).map(nfc);
-    const every = Object.values(given).filter(Array.isArray).flat().map(nfc);
+    const every = (
+        Array.isArray(given) ? given : Object.values(given).filter(Array.isArray).flat()).map(nfc);
     const lookup = (forGiven) => (part) =>
         part.list === GIVEN_LIST && part.gender === undefined ?
             forGiven

package/engine/markdownlint-run.mjs

@@ -669,7 +669,7 @@ function protectLintVerse(source) {
     };
     for (const region of verseRegions(syntax)) {
         if (!region.closed) continue;
-        referencesInVerse(region.body, parseVerse(region.body, { footnotes }));
+        referencesInVerse(region.logicalBody, parseVerse(region.logicalBody, { footnotes }));
         ranges.push([region.bodyStart, starts[region.end]]);
         for (let line = region.start + 1; line < region.end; line++) {
             bodyLines.add(line + 1);

package/engine/markup-validation.mjs

@@ -11,6 +11,7 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
+import { scanPageBreaks } from "./page-breaks.mjs";
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanAlerts } from "./content-alerts.mjs";
 import { scanRuns } from "./content-scripts.mjs";
@@ -74,6 +75,7 @@ export function markupFindings(source, file, syntax, runs) {
     const errors = [
         ...(scanned?.blocks ?? scanBlocks(body)).errors,
         ...(scanned?.alerts ?? scanAlerts(body)).errors,
+        ...scanPageBreaks(body).errors,
         ...verseErrors,
         ...(marked?.errors ?? []),
         ...shortcodeErrors(body),

package/engine/note-vocabulary.mjs

@@ -771,7 +771,7 @@ const NAMES_FIELD = Object.freeze({
     describe:
         "How this language's speakers are named, for `package-build npc new`: `pattern` " +
         'builds a name from placeholders such as "{given} {clan}" and literal text, `given` ' +
-        "maps a gender to a list of given names, " +
+        "is one list of given names for everyone or a map by gender with " +
         `${wordList([...requiredGivenGenders()]).replace(" or ", " and ")} required, and ` +
         "`en` holds groups of English names, and every other key is a list of names a " +
         "placeholder of the same name draws from. A " +
@@ -807,12 +807,17 @@ const NAMES_FIELD = Object.freeze({
         }),
         Object.freeze({
             name: "given",
-            kind: "map",
+            kind: "list-or-map",
             required: true,
-            shape: "a map of genders to lists of names",
+            shape: "a list of names or a map of genders to lists of names",
             describe:
-                "Given names by gender word. A gender with no list draws from every given " +
-                "list together.",
+                "One shared list supplies every gender. A gender map requires female and male; " +
+                "a gender with no list draws from every given list together.",
+            entries: Object.freeze({
+                kind: "string",
+                shape: "a name",
+                describe: "One name, as written.",
+            }),
             values: Object.freeze({
                 kind: "list",
                 shape: "a list of names",

package/engine/npc-generate.mjs

@@ -32,9 +32,11 @@
  *
  * - `name.full` — drawn from the culture's language's name lists by their
  *   pattern, the given name from the list for `data.gender` (see
- *   `language-names.mjs`). A name the spec states is kept, and must fit those
- *   lists: every placeholder filled by a name of its list, the given name from
- *   the gender's.
+ *   `language-names.mjs`). Each drawn name word starts with a capital in the
+ *   English display form; the pattern's literal connectors keep their case.
+ *   A different source form with no English list part is retained under the
+ *   language code. A name the spec states is kept, and must fit the source or
+ *   display-form lists.
  * - `shortcode` — the name transliterated to lowercase ASCII letters and
  *   digits, cut to twelve characters, with a counter replacing its tail where a
  *   being in the package already holds it.
@@ -70,7 +72,7 @@ import { parseNoteDate } from "./note-dates.mjs";
 import { eraYear } from "./calendars.mjs";
 import { parseAddress, renderAddress } from "./address.mjs";
 import { isPlainMap } from "./data-keys.mjs";
-import { drawName, nameMisfit } from "./language-names.mjs";
+import { drawNameParts, nameMisfit } from "./language-names.mjs";
 
 /** The youngest and oldest age, in whole years, a generated person is born to. */
 export const ADULT_AGE = Object.freeze({ min: 18, max: 60 });
@@ -152,6 +154,27 @@ export function canonicalSpec(value) {
 /** Whether a spec value counts as given — any value but `undefined`. */
 const given = (value) => value !== undefined;
 
+/** Each name word starts with a capital and keeps its remaining letters. */
+const displayNameWords = (name) =>
+    name.replace(/\p{L}[\p{L}\p{M}'’]*/gu, (word) =>
+        word.replace(/^\p{L}/u, (letter) => letter.toUpperCase()),
+    );
+
+/** Name lists in English display case; literal pattern text keeps its case. */
+function displayNameLists(names) {
+    const display = (value) =>
+        Array.isArray(value) ? value.map(displayNameWords)
+        : isPlainMap(value) ?
+            Object.fromEntries(Object.entries(value).map(([key, list]) => [key, display(list)]))
+        :   value;
+    return Object.fromEntries(
+        Object.entries(names).map(([key, value]) => [
+            key,
+            key === "pattern" ? value : display(value),
+        ]),
+    );
+}
+
 /** The value at a dotted path, or `undefined`. */
 function at(object, path) {
     let value = object;
@@ -433,6 +456,8 @@ function frontmatterYaml(frontmatter) {
  *   by `namesProblems`.
  * @param {string} [context.language] - The language's Address, for an error
  *   about a name that does not fit.
+ * @param {string} [context.languageCode] - The language code under which a
+ *   generated name's distinct source form is retained.
  * @param {string} [context.seed] - Text joined to the spec's own seed, to draw a
  *   different person from the same spec.
  * @param {unknown} [context.currentDate] - The setting's neutral current date, defaulting to "720.1".
@@ -460,7 +485,9 @@ export function generateNpc(spec, context) {
     const gender = data.gender;
     const statedName = spec.name?.full;
     if (given(statedName)) {
-        const misfit = nameMisfit(statedName, names, gender);
+        const displayNames = displayNameLists(names);
+        const misfit =
+            nameMisfit(statedName, names, gender) && nameMisfit(statedName, displayNames, gender);
         if (misfit)
             throw Object.assign(
                 new Error(
@@ -470,7 +497,25 @@ export function generateNpc(spec, context) {
                 { keyPath: ["name", "full"] },
             );
     }
-    const name = given(statedName) ? statedName : drawName(names, gender, draw("name.full"));
+    const nameParts = given(statedName) ? [] : drawNameParts(names, gender, draw("name.full"));
+    const sourceName = given(statedName) ? statedName : nameParts.map((part) => part.text).join("");
+    const name =
+        given(statedName) ? statedName : (
+            nameParts
+                .map((part) => ("literal" in part ? part.text : displayNameWords(part.text)))
+                .join("")
+        );
+    const languageCode = context.languageCode;
+    const sourceAlias =
+        (
+            !given(statedName) &&
+            languageCode &&
+            languageCode !== "en" &&
+            sourceName !== name &&
+            !nameParts.some((part) => "list" in part && part.list === "en")
+        ) ?
+            { [languageCode]: [sourceName] }
+        :   {};
 
     const height =
         given(data.height) ?
@@ -537,7 +582,7 @@ export function generateNpc(spec, context) {
             subType: "npc",
             tags: ["generated", "draft"],
             ...frontmatterSpec,
-            name: { full: name, ...(isPlainMap(spec.name) ? spec.name : {}) },
+            name: { full: name, ...sourceAlias, ...(isPlainMap(spec.name) ? spec.name : {}) },
             data: fullData,
         },
         TOP_ORDER,

package/engine/page-breaks.mjs

@@ -0,0 +1,115 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/** Authored book page breaks and their positioned syntax findings. @module */
+
+import { blockTokens } from "./markdown-blocks.mjs";
+import { scanBlocks } from "./content-blocks.mjs";
+import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+
+/** A standalone attributed break, including Markdown container prefixes. */
+const BREAK_LINE =
+    /^(?:[ \t]*(?:>[ \t]?|(?:[-+*]|\d{1,9}[.)])[ \t]+))*[ \t]*(---|\*\*\*|___)[ \t]+(\{[^\r\n]*\})[ \t]*$/;
+const PLACEMENT = "a page break stands between blocks at the top level of a note";
+
+/**
+ * Read page-break markers before any surface rewrites their source.
+ * Code, HTML examples and entire verse divs remain literal. Parser ranges
+ * retain list and quote membership, including lazy continuation lines.
+ * @param {string} source - Authored Markdown body.
+ * @returns {{breaks: Array<{line: number, column: number}>, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanPageBreaks(source) {
+    const text = String(source ?? "");
+    const lines = text.split(/\r?\n/);
+    if (!lines.some((line) => BREAK_LINE.test(line))) return { breaks: [], errors: [] };
+    const literal = new Set();
+    const nested = new Set();
+    for (const token of blockTokens(text)) {
+        if (!token.map) continue;
+        const target =
+            ["fence", "code_block", "html_block", "verse_div"].includes(token.type) ? literal
+            : ["blockquote_open", "list_item_open"].includes(token.type) ? nested
+            : undefined;
+        if (target) for (let line = token.map[0]; line < token.map[1]; line++) target.add(line);
+    }
+    for (const block of scanBlocks(text).blocks)
+        for (let line = block.start + 1; line < block.end; line++) nested.add(line);
+    const breaks = [],
+        errors = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (literal.has(i)) continue;
+        const match = BREAK_LINE.exec(lines[i]);
+        if (!match) continue;
+        const parsed = parseExtensionAttributes(match[2].slice(1, -1));
+        if (match[1] !== "---" && !parsed.classes.includes("page-break")) continue;
+        const column = lines[i].indexOf(match[1]) + 1;
+        const attributeColumn = lines[i].indexOf("{") + 1;
+        const at = (message) => ({ line: i + 1, column: attributeColumn, message });
+        const problems = [...parsed.problems, ...refusedAttributes(parsed.values)];
+        if (
+            parsed.classes.some((name) => name !== "page-break") ||
+            (!parsed.classes.length &&
+                !parsed.id &&
+                !Object.keys(parsed.values).length &&
+                !problems.length)
+        )
+            problems.push("a page break accepts only .page-break");
+        if (parsed.id) problems.push("a page break does not accept an id");
+        if (Object.keys(parsed.values).length)
+            problems.push("a page break does not accept attributes");
+        if (match[1] !== "---")
+            errors.push({ line: i + 1, column, message: "only --- accepts {.page-break}" });
+        if (
+            nested.has(i) ||
+            (i > 0 && lines[i - 1].trim()) ||
+            (i + 1 < lines.length && lines[i + 1].trim())
+        )
+            errors.push({ line: i + 1, column, message: PLACEMENT });
+        errors.push(...problems.map(at));
+        if (match[1] === "---" && !problems.length && !errors.some((error) => error.line === i + 1))
+            breaks.push({ line: i + 1, column });
+    }
+    return { breaks, errors };
+}
+
+/**
+ * Omit valid page breaks on a screen, preserving the surrounding block boundaries.
+ * @param {string} source - Markdown body.
+ * @returns {string} Markdown without valid page-break lines.
+ */
+export function omitPageBreaks(source) {
+    const lines = String(source ?? "").split("\n");
+    for (const marker of scanPageBreaks(source).breaks) lines[marker.line - 1] = "";
+    return lines.join("\n");
+}
+
+/**
+ * Produce the book's page-break token, leaving ordinary thematic breaks alone.
+ * @param {import("markdown-it")} md - The book parser.
+ * @returns {void}
+ */
+export function pageBreakPlugin(md) {
+    md.block.ruler.before("hr", "page_break", (state, startLine, _endLine, silent) => {
+        if (state.env.pageBreaks === false) return false;
+        const line = state.src.slice(state.bMarks[startLine], state.eMarks[startLine]);
+        if (!BREAK_LINE.test(line)) return false;
+        if (!scanPageBreaks(state.src).breaks.some((marker) => marker.line === startLine + 1))
+            return false;
+        if (silent) return true;
+        const token = state.push("page_break", "", 0);
+        token.map = [startLine, startLine + 1];
+        state.line = startLine + 1;
+        return true;
+    });
+}

package/engine/pdf-build.mjs

@@ -1385,7 +1385,9 @@ async function buildBook(book, shared) {
                 url: site,
                 elsewhere,
                 findings,
-                runs: runContext(resolved, records),
+                runs: runContext(resolved, records, {
+                    referenceName: (target) => resolveInfoboxRef(gates.index, target)?.name,
+                }),
                 file: page.file,
                 bodyLine: page.bodyLine,
                 prepared: true,
@@ -1476,7 +1478,9 @@ async function buildBook(book, shared) {
                     elsewhere,
                     indexMentions: true,
                     findings,
-                    runs: runContext(resolved, records),
+                    runs: runContext(resolved, records, {
+                        referenceName: (target) => resolveInfoboxRef(gates.index, target)?.name,
+                    }),
                     file,
                 }),
             );
@@ -1508,7 +1512,9 @@ async function buildBook(book, shared) {
                 elsewhere,
                 indexMentions: true,
                 findings,
-                runs: runContext(resolved, records),
+                runs: runContext(resolved, records, {
+                    referenceName: (target) => resolveInfoboxRef(gates.index, target)?.name,
+                }),
                 file,
             });
         } catch {
@@ -1682,7 +1688,9 @@ async function buildBook(book, shared) {
         copyright: shared.copyright,
         license: shared.license,
         index,
-        runs: runContext(resolved, records),
+        runs: runContext(resolved, records, {
+            referenceName: (target) => resolveInfoboxRef(gates.index, target)?.name,
+        }),
     });
     // Last, over the whole document: a reference can only be checked once every
     // declaration is in one string, and Typst treats a dangling one as fatal.