@heroiclands/package-build 25.5.4 → 25.6.0

package/engine/language-terms.mjs

@@ -152,8 +152,12 @@ export const JOIN_MEETINGS = Object.freeze(["C+C", "V+C", "V+V"]);
  */
 export const JOIN_RULES = Object.freeze(["merge", "insert", "drop", "double"]);
 
-/** What a written mark says of its letter. */
-export const MARK_KINDS = Object.freeze(["stress", "length", "apart"]);
+/**
+ * What a written mark says of its letter: `stress` falls on it, `length` holds
+ * it longer, `apart` says it apart from its neighbour, and `quality` changes
+ * which vowel is said.
+ */
+export const MARK_KINDS = Object.freeze(["stress", "length", "apart", "quality"]);
 
 /** How many of a mark a word may carry: `one` at most, or `any` number. */
 export const MARK_LIMITS = Object.freeze(["one", "any"]);
@@ -320,13 +324,6 @@ export const SCOPE_FIELDS = Object.freeze([
         entries: Object.freeze({ kind: "address", shape: "an Address" }),
         describe: "These notes themselves.",
     }),
-    Object.freeze({
-        name: "paths",
-        kind: "list",
-        shape: "a list of content paths",
-        entries: Object.freeze({ kind: "string", shape: "a path such as `Regions/Aelwyth/`" }),
-        describe: "Every note whose file sits below one of these paths of the content tree.",
-    }),
     Object.freeze({
         name: "types",
         kind: "list",
@@ -1926,7 +1923,7 @@ export const LANGUAGE_DATA_FIELDS = Object.freeze([
     Object.freeze({
         name: "scope",
         kind: "map",
-        shape: "a map — `{ folders?, cultures?, lore?, parents?, addresses?, paths?, types?, skip? }`",
+        shape: "a map — `{ folders?, cultures?, lore?, parents?, addresses?, types?, skip? }`",
         fields: SCOPE_FIELDS,
         describe: "The notes the register covers. A language skill note only.",
     }),

package/engine/map-dot.mjs

@@ -131,6 +131,26 @@ export const STYLE = Object.freeze({
         penwidth: 2.0,
         extraStyle: "rounded",
     },
+    district: {
+        shape: "box",
+        fill: "#C5E1A5",
+        border: DEFAULT_BORDER,
+        fontsize: 9,
+        width: 0.8,
+        height: 0.4,
+        penwidth: 1.0,
+        extraStyle: "rounded,dashed",
+    },
+    route: {
+        shape: "parallelogram",
+        fill: "#FFE082",
+        border: DEFAULT_BORDER,
+        fontsize: 9,
+        width: 0.9,
+        height: 0.4,
+        penwidth: 1.0,
+        extraStyle: "",
+    },
     settlement: {
         shape: "ellipse",
         fill: "#A5D6A7",
@@ -187,10 +207,12 @@ export const STYLE = Object.freeze({
 const LEGEND = Object.freeze([
     ["world", "the root note"],
     ["region", "continent, region, sub-region"],
+    ["district", "quarter, ward, shire"],
     ["settlement", "city, town, village"],
     ["site", "ruin, landmark, dungeon, wonder"],
     ["feature", "river, mountain range, sea"],
     ["structure", "a single building"],
+    ["route", "road, pass, sea lane"],
     ["polity", "affiliation, dashed edge to its region"],
 ]);
 

package/engine/markdown-blocks.mjs

@@ -25,35 +25,50 @@
  */
 
 import MarkdownIt from "markdown-it";
+import footnotePlugin from "markdown-it-footnote";
 import { verseDivPlugin } from "./verse-regions.mjs";
 
 /** The renderer's block grammar, with inline parsing and its passes switched off. */
 const parser = new MarkdownIt({ html: true }).use(verseDivPlugin);
-parser.core.ruler.disable(["inline", "linkify", "replacements", "smartquotes", "text_join"]);
+const footnoteParser = new MarkdownIt({ html: true }).use(footnotePlugin).use(verseDivPlugin);
+for (const projection of [parser, footnoteParser])
+    projection.core.ruler.disable([
+        "inline",
+        "linkify",
+        "replacements",
+        "smartquotes",
+        "text_join",
+    ]);
+// Keep definition containers and their original maps in place for scanners.
+footnoteParser.core.ruler.disable("footnote_tail");
 
 /** How many recent sources keep their tokens. */
 const RECENT = 16;
 
 /** @type {Map<string, import("markdown-it").Token[]>} */
 const recent = new Map();
+const recentFootnotes = new Map();
 
 /**
  * The block tokens of a Markdown source. The array is shared between callers
  * and must not be modified; an `inline` token carries no `children`.
  *
  * @param {unknown} source - Markdown.
+ * @param {object} [options] - Optional block projection.
+ * @param {boolean} [options.footnotes=false] - Include footnote definition containers.
  * @returns {readonly import("markdown-it").Token[]} The block tokens, in order.
  */
-export function blockTokens(source) {
+export function blockTokens(source, { footnotes = false } = {}) {
     const text = String(source ?? "");
-    const hit = recent.get(text);
+    const cache = footnotes ? recentFootnotes : recent;
+    const hit = cache.get(text);
     if (hit) {
-        recent.delete(text);
-        recent.set(text, hit);
+        cache.delete(text);
+        cache.set(text, hit);
         return hit;
     }
-    const tokens = parser.parse(text, { verseSource: text });
-    recent.set(text, tokens);
-    if (recent.size > RECENT) recent.delete(recent.keys().next().value);
+    const tokens = (footnotes ? footnoteParser : parser).parse(text, { verseSource: text });
+    cache.set(text, tokens);
+    if (cache.size > RECENT) cache.delete(cache.keys().next().value);
     return tokens;
 }

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/metadata-index.mjs

@@ -507,6 +507,7 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                     }
                 :   {}),
                 population: record.data?.population ?? undefined,
+                market: record.data?.market ?? undefined,
                 ...(Object.hasOwn(record.data ?? {}, "government") ?
                     { government: record.data.government }
                 :   {}),

package/engine/note-addresses.mjs

@@ -43,6 +43,22 @@ export {
 
 /** Structured positions whose Address is nested inside a declared container. */
 export const STRUCTURED_ADDRESSES = Object.freeze([
+    {
+        noteType: "place",
+        path: ["data", "settlements", "rows", "*", "place"],
+        shape: "value",
+        type: "place",
+        accepts: ["place"],
+        lenient: true,
+    },
+    {
+        noteType: "place",
+        path: ["data", "settlements", "rows", "*", "heldBy"],
+        shape: "value",
+        type: "affiliation",
+        accepts: ["affiliation", "being"],
+        lenient: true,
+    },
     { path: ["data", "seeAlso", "*", "address"], shape: "value", lenient: true },
     {
         path: ["packFolder"],

package/engine/note-vocabulary.mjs

@@ -104,6 +104,8 @@ import {
     STANDING_FIELDS,
 } from "./standing-terms.mjs";
 import { checkDatedOffices } from "./office-holders.mjs";
+import { checkUniqueItem } from "./unique-items.mjs";
+import { checkPlaceKind } from "./place-kinds.mjs";
 import { checkAffiliationRankFloor, checkRankLadder } from "./rank-ladder.mjs";
 import { checkCalendarChoice } from "./calendar-choice.mjs";
 import { checkNoteEvents } from "./note-events.mjs";
@@ -160,6 +162,7 @@ import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkSettlementTables } from "./settlement-tables.mjs";
+import { SETTLEMENTS_FIELD } from "./settlement-terms.mjs";
 import { checkConceptList, checkCoreFlag } from "./core-vocabulary.mjs";
 import { METRE_KINDS, checkMetresField } from "./metre-declaration.mjs";
 import { checkLanguageEmphasis, checkScriptField } from "./script-emphasis.mjs";
@@ -771,7 +774,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 +810,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",
@@ -1246,8 +1254,8 @@ const EVENT_ADDRESS = Object.freeze({
 });
 
 /**
- * The values every carried thing declares: the four a game reads, and the two
- * events of its history.
+ * The values every carried thing declares: the four a game reads, the two
+ * events of its history, and whether it is the only one of its kind.
  *
  * @type {readonly DataFieldSpec[]}
  */
@@ -1270,6 +1278,15 @@ const GEAR = Object.freeze([
             "The event in which the thing was lost — `lore-flood`, or one event of a note " +
             "as `place-ironfells#sack`.",
     },
+    {
+        name: "unique",
+        kind: "boolean",
+        shape: "`true` or `false`",
+        check: checkUniqueItem,
+        describe:
+            "`true` for a one-of-a-kind item, such as a named weapon; its note links the " +
+            "places and beings involved. Absent, the item is common.",
+    },
 ]);
 
 /** Gear that is counted rather than carried singly. */
@@ -1299,7 +1316,7 @@ const CHARGES = Object.freeze([
  * Three questions about one subject, and they are independent: who governs
  * this inhabited place, what the body states about itself where the note is a
  * body rather than somewhere within one, and whether a region's settlements
- * table agrees with its holding model and the notes it links. A type declares
+ * table agrees with the notes it links. A type declares
  * one whole-note check, so the three are composed here rather than any being
  * folded into another.
  *
@@ -1312,6 +1329,7 @@ function checkPlace(note, opts) {
         ...checkGovernment(note),
         ...checkWorldFacts(note, opts),
         ...checkSettlementTables(note, opts),
+        ...checkPlaceKind(note, opts),
     ];
 }
 
@@ -2492,10 +2510,12 @@ export const NOTE_VOCABULARY = Object.freeze({
         subTypes: Object.freeze([
             "world",
             "region",
+            "district",
             "settlement",
             "site",
             "structure",
             "feature",
+            "route",
             "celestial",
         ]),
         check: checkPlace,
@@ -2551,6 +2571,7 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "Explicit null means complete anarchy. " +
                     "A positive population with no government key produces an advisory.",
             },
+            SETTLEMENTS_FIELD,
             {
                 name: "market",
                 ...NUM,
@@ -2633,11 +2654,6 @@ export const NOTE_VOCABULARY = Object.freeze({
                 accepts: ["scenario"],
                 describe: "Scenarios that should be played before this one.",
             },
-            {
-                name: "status",
-                ...TEXT,
-                describe: "`draft`, `playtested` or `published`.",
-            },
             {
                 name: "party.size",
                 ...TEXT,

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/office-holders.mjs

@@ -17,9 +17,85 @@ import { parseNoteDate } from "./note-dates.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 
 import { HOLDER_FIELDS, OFFICE_FIELDS } from "./standing-terms.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { isAddressTuple } from "./address.mjs";
+import { officeRoster, readStandings, standingOffices } from "./standings.mjs";
 
 export { HOLDER_FIELDS, OFFICE_FIELDS };
 
+/**
+ * A note's identity across its systems: `package-type-shortcode`, lowercased.
+ *
+ * A body's Item and its journal carry one page, and a being names the body by
+ * its `note` Address, so the system is left out.
+ *
+ * @param {{package?: string, type?: string, shortcode?: string}} tuple
+ * @returns {string} The key, or `""` where a part is missing.
+ */
+export function officeBodyKey(tuple) {
+    const parts = [tuple?.package, tuple?.type, tuple?.shortcode].map((part) =>
+        String(part ?? "").toLowerCase(),
+    );
+    return parts.every(Boolean) ? parts.join("-") : "";
+}
+
+/**
+ * Each body's offices with the living beings that hold them.
+ *
+ * Nothing is authored on the office for this: a being states the post it holds
+ * in its own `data.affiliations.<body>.office`, and this collects, for every
+ * office in a body's `governance.offices`, each being naming it. A being whose
+ * `data.died` is set holds nothing, so a former holder drops out and a vacant
+ * office lists no one. A post the body does not declare is the standing check's
+ * finding and is listed nowhere.
+ *
+ * Offices keep the body's declared order; holders are ordered by name.
+ *
+ * @param {object[]} records - Content-index records; only note records are
+ *   read.
+ * @returns {Map<string, Map<string, object[]>>} Body identity
+ *   (`package-type-shortcode`) → office → the holding beings' records, for every
+ *   body with at least one held office.
+ */
+export function officeHolders(records) {
+    const notes = records.filter((record) => isNoteRecord(record) && record.shortcode);
+    /** Body identity → office → holding beings. */
+    const named = new Map();
+    for (const record of notes) {
+        if (record.type !== "being" || record.data?.died != null) continue;
+        for (const { body, standing } of readStandings(record.data?.affiliations).entries) {
+            const key = isAddressTuple(body) ? officeBodyKey(body) : "";
+            if (!key || !mapping(standing)) continue;
+            const offices = named.get(key) ?? new Map();
+            for (const office of standingOffices(standing)) {
+                const holders = offices.get(office) ?? [];
+                if (!holders.includes(record)) holders.push(record);
+                offices.set(office, holders);
+            }
+            named.set(key, offices);
+        }
+    }
+    const nameOf = (record) => String(record.name?.full ?? record.shortcode);
+    const out = new Map();
+    for (const record of notes) {
+        if (record.type !== "affiliation") continue;
+        const key = officeBodyKey(record);
+        const claims = named.get(key);
+        if (!claims) continue;
+        const held = new Map();
+        for (const office of officeRoster(record.data?.governance?.offices).keys()) {
+            const holders = claims.get(office);
+            if (holders?.length)
+                held.set(
+                    office,
+                    holders.toSorted((a, b) => nameOf(a).localeCompare(nameOf(b), "en")),
+                );
+        }
+        if (held.size) out.set(key, held);
+    }
+    return out;
+}
+
 const mapping = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
 /**

package/engine/page-breaks.mjs

@@ -0,0 +1,143 @@
+/*
+ * 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 =
+    /^(?<prefix>(?:[ \t]*(?:>[ \t]?|(?:[-+*]|\d{1,9}[.)])[ \t]+|\[\^[^\]\s]+\]:[ \t]*))*[ \t]*)(?<marker>---|\*\*\*|___)[ \t]+(?<attributes>\{[^\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();
+    let footnoteDepth = 0;
+    for (const token of blockTokens(text, { footnotes: true })) {
+        if (token.type === "footnote_reference_open") footnoteDepth++;
+        if (token.type === "footnote_reference_close") footnoteDepth--;
+        if (!token.map) continue;
+        if (footnoteDepth)
+            for (let line = token.map[0]; line < token.map[1]; line++) nested.add(line);
+        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 { prefix, marker, attributes } = match.groups;
+        const parsed = parseExtensionAttributes(attributes.slice(1, -1));
+        if (marker !== "---" && !parsed.classes.includes("page-break")) continue;
+        const column = prefix.length + 1;
+        const attributeColumn = lines[i].lastIndexOf(attributes) + 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 (marker !== "---")
+            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 (marker === "---" && !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");
+}
+
+/**
+ * Preserve refused markers as literal Markdown before the book slices blocks.
+ * A slice must not make a marker eligible by discarding its original neighbour.
+ * Findings are collected from the original source before this rewrite.
+ * @param {string} source - Complete Markdown body, before splitting containers.
+ * @returns {string} Markdown with invalid markers escaped for literal rendering.
+ */
+export function escapeInvalidPageBreaks(source) {
+    const text = String(source ?? "");
+    const refused = new Set(scanPageBreaks(text).errors.map((error) => error.line));
+    if (!refused.size) return text;
+    return text
+        .split("\n")
+        .map((line, i) => {
+            if (!refused.has(i + 1)) return line;
+            const match = BREAK_LINE.exec(line.replace(/\r$/, ""));
+            const prefix = match.groups.prefix;
+            return `${prefix}\\${line.slice(prefix.length)}`;
+        })
+        .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;
+    });
+}