@heroiclands/package-build 25.5.4 → 25.6.0

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.

package/engine/pdf-render.mjs

@@ -62,6 +62,7 @@
  * @module
  */
 
+import { escapeInvalidPageBreaks, scanPageBreaks } from "./page-breaks.mjs";
 import { createRenderer } from "./content-render.mjs";
 import { bookDraftNoticePreamble } from "./draft-notice.mjs";
 import { ICON_PATTERN, ICON_SIZES } from "./content-icons.mjs";
@@ -359,6 +360,7 @@ function reportUnrenderable(source, definitions, opts, original) {
         }
     }
     for (const error of [
+        ...scanPageBreaks(original).errors,
         ...scanSpans(source).errors,
         ...scanRuns(source, opts.runs).errors,
         ...markupAnchorFindings(source),
@@ -469,6 +471,7 @@ function reportUnrenderable(source, definitions, opts, original) {
  * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - From
  *   table expansion, mapping each line handed in back to the line an author
  *   wrote.
+ * @param {boolean} [opts.pageBreaks] - Internal: whether this slice remains at the note top level.
  * @param {boolean} [opts.prepared] - Whether this body has been through the
  *   passes that resolve a wikilink, an embed and an inline expression. A note's
  *   has; a front-matter file's and a prose file's have not, and markup of theirs
@@ -519,7 +522,8 @@ export function markdownToTypst(markdown, opts = {}) {
             renderRuns(markingSource, opts.runs, undefined, { target: "book" })
         );
     const markedFootnotes = marked && definitions ? separateFootnotes(marked.markdown) : undefined;
-    const source = markedFootnotes?.markdown ?? marked?.markdown ?? authored;
+    const markedSource = markedFootnotes?.markdown ?? marked?.markdown ?? authored;
+    const source = opts.nested ? markedSource : escapeInvalidPageBreaks(markedSource);
     if (markedFootnotes) definitions = markedFootnotes.definitions;
     if (marked) {
         sharedOptions.footnoteDefinitions = definitions;
@@ -547,6 +551,7 @@ export function markdownToTypst(markdown, opts = {}) {
         footnotePrefix: opts.footnotePrefix ?? `footnote-${slugify(anchorPrefix || "body")}`,
         scrolls: marked?.scrolls ?? opts.scrolls ?? new Map(),
         verses: marked?.verses ?? opts.verses ?? new Map(),
+        pageBreaks: opts.pageBreaks !== false,
     };
     // A withheld section is set in the box a `:::secret` is set in, and its
     // heading is set inside it: a printed page honours no reader permission, so
@@ -600,6 +605,7 @@ export function markdownToTypst(markdown, opts = {}) {
                 if (block.name === "div") {
                     const content = markdownToTypst(block.body, {
                         ...sharedOptions,
+                        pageBreaks: false,
                         insideAdmonition: false,
                     });
                     const anchor = block.id ? ` <${sectionLabel(anchorPrefix, block.id)}>` : "";
@@ -620,6 +626,7 @@ export function markdownToTypst(markdown, opts = {}) {
                 // of its own; a box holds none, and the scan has already said so.
                 const content = markdownToTypst(block.body, {
                     ...sharedOptions,
+                    pageBreaks: false,
                     insideAdmonition: !BLOCK_CONTAINERS.includes(block.name),
                 });
                 output.push(
@@ -695,7 +702,7 @@ export function markdownToTypst(markdown, opts = {}) {
 /** Render one fragment with the note's footnote definitions available. */
 function renderMarkdownSegment(source, md, ctx, definitions) {
     const input = definitions ? `${source}\n\n${definitions}` : source;
-    const tokens = md.parse(input, { verses: ctx.verses });
+    const tokens = md.parse(input, { verses: ctx.verses, pageBreaks: ctx.pageBreaks });
     const footnoteStart = tokens.findIndex((token) => token.type === "footnote_block_open");
     const visible = footnoteStart < 0 ? tokens : tokens.slice(0, footnoteStart);
     const footnotes = new Map();
@@ -791,6 +798,9 @@ function renderBlock(tokens, i, out, ctx) {
             out.push(`\n#block(width: 100%)[${content}]${anchor}\n`);
             return 1;
         }
+        case "page_break":
+            out.push("\n#pagebreak(weak: true)\n\n");
+            return 1;
         case "hr":
             out.push("\n#line(length: 100%, stroke: 0.4pt)\n\n");
             return 1;

package/engine/place-kinds.mjs

@@ -0,0 +1,106 @@
+/*
+ * 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
+ */
+
+/**
+ * **What a district and a route require of their notes.**
+ *
+ * A `place/district` is a recognised division of a larger place, usually
+ * administrative: a city's quarter, a town's ward, a kingdom's shire. It always
+ * stands within a `place/settlement` or a `place/region`, named in
+ * `data.parents`. It may name its own governing affiliation in
+ * `data.government`; without one it falls under its parent's government.
+ *
+ * A `place/route` is a road, a pass or a sea lane, and the journeys it carries
+ * are its `data.routes`.
+ *
+ * @module
+ */
+
+import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/** The place kinds a district may stand within. */
+export const DISTRICT_PARENT_KINDS = Object.freeze(["settlement", "region"]);
+
+/**
+ * The place one `parents` entry names, as the lint's index holds it.
+ *
+ * @param {unknown} value - The authored entry.
+ * @param {object} [index] - The lint's address index.
+ * @returns {{resolved: boolean, fm?: object}} Whether it resolves, and its
+ *   frontmatter where it does.
+ */
+function parentOf(value, index) {
+    const tuple =
+        isAddressTuple(value) ? value : (
+            parseAddress(value, {
+                package: index?.contentPackage,
+                system: "note",
+                type: "place",
+                types: index?.types,
+                packages: index?.packages,
+            })
+        );
+    if (!isAddressTuple(tuple) || !index?.addressHit) return { resolved: false };
+    const hit = index.addressHit(renderAddress({ ...tuple, system: "note" }));
+    return hit ? { resolved: true, fm: hit.fm ?? hit } : { resolved: false };
+}
+
+/**
+ * Check a district's parent and a route's journeys.
+ *
+ * A district naming no parent is reported at its `subType`; one whose parents
+ * all resolve and none is a settlement or a region is reported at `parents`.
+ * A parent that does not resolve is the Address check's finding, so a district
+ * whose only parents are unresolved earns nothing more here. A route stating no
+ * `data.routes` entry is reported at its `subType`.
+ *
+ * @param {object} note - The note: `file`, `raw` and parsed `fm`.
+ * @param {{index?: object}} [options] - The lint's options.
+ * @returns {object[]} Located findings.
+ */
+export function checkPlaceKind(note, { index } = {}) {
+    const subType = note.fm?.subType;
+    const at = (path, key) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(note.raw ?? "", path, key ? { key: true } : undefined),
+        severity: "error",
+    });
+    if (subType === "district") {
+        const parents = note.fm?.data?.parents;
+        const list =
+            Array.isArray(parents) ? parents
+            : parents == null ? []
+            : [parents];
+        const message =
+            "a district stands within a settlement or a region; name one in `data.parents`";
+        if (!list.length) return [{ ...at(["subType"]), message }];
+        const found = list.map((value) => parentOf(value, index));
+        if (found.some((one) => !one.resolved)) return [];
+        if (found.some((one) => DISTRICT_PARENT_KINDS.includes(one.fm?.subType))) return [];
+        return [{ ...at(["data", "parents"], true), message }];
+    }
+    if (subType === "route") {
+        const routes = note.fm?.data?.routes;
+        if (Array.isArray(routes) && routes.length) return [];
+        return [
+            {
+                ...at(["subType"]),
+                message:
+                    "a route carries its journeys in `data.routes`; state at least one, " +
+                    "each `{ to, bearing, mode, days }`",
+            },
+        ];
+    }
+    return [];
+}

package/engine/preview-index.mjs

@@ -37,7 +37,7 @@ import { noContentIndexPackages } from "./metadata-index.mjs";
 import { isGmNote } from "./note-vocabulary.mjs";
 import { assetAddressIndex } from "./art-fields.mjs";
 import { assetPathnameKey, pathnameProblem, resolvePathname } from "./pathnames.mjs";
-import { buildSiteIndex } from "./site-index.mjs";
+import { buildSiteIndex, resolveInfoboxRef } from "./site-index.mjs";
 import { siteBase } from "../content-config.mjs";
 
 /**
@@ -107,7 +107,9 @@ export function previewIndex({ config, records, foreign }) {
         return key ? assets?.byPath?.get(key) : undefined;
     };
     return {
-        runs: runContext(config, records),
+        runs: runContext(config, records, {
+            referenceName: (target) => resolveInfoboxRef(site, target)?.name,
+        }),
         icons: config.icons,
         lookupAsset,
         resolveSrc: webSrc,