@heroiclands/package-build 23.11.0 → 23.12.0

package/engine/current-date.mjs

@@ -0,0 +1,37 @@
+/*
+ * 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
+ */
+
+/** Setting-wide neutral current date, independent of configuration loading. */
+import { parseNoteDate } from "./note-dates.mjs";
+
+/** Default day on the neutral setting timeline. */
+export const DEFAULT_CURRENT_DATE = "720.1";
+
+/**
+ * Validate a quoted neutral date and preserve its authored day digits.
+ * @param {unknown} [value] - Explicit configuration or adapter override.
+ * @returns {string} Validated neutral date; undefined selects the default.
+ * @throws {TypeError} An explicit value is not a valid neutral date string.
+ */
+export function normalizeCurrentDate(value = undefined) {
+    if (value === undefined) return DEFAULT_CURRENT_DATE;
+    if (typeof value !== "string" || !/^-?\d+(?:\.\d+)?(?::\d{6})?$/.test(value.trim()))
+        throw new TypeError('currentDate must be a quoted neutral date: "<year>[.<day>[:HHMMSS]]"');
+    const text = value.trim();
+    const parsed = parseNoteDate(text, { allowUnknown: false });
+    if (!parsed.date || parsed.findings.some((finding) => finding.severity === "error"))
+        throw new TypeError(
+            `currentDate: ${parsed.findings[0]?.message ?? "invalid neutral date"}`,
+        );
+    return text;
+}

package/engine/definition-list.mjs

@@ -0,0 +1,58 @@
+/*
+ * 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
+ */
+
+/** Semantic dictionary rows for HTML definition lists. @module */
+
+/**
+ * Group each term and its definitions without reparsing their Markdown tokens.
+ * Register after markdown-it-deflist; nested blocks and footnotes retain their
+ * document context.
+ * @param {import("markdown-it")} md - An HTML Markdown parser with definition lists.
+ */
+export function dictionaryListPlugin(md) {
+    md.core.ruler.push("dictionary_list_rows", (state) => {
+        const output = [],
+            lists = [];
+        const row = (nesting) => {
+            const token = new state.Token(
+                nesting === 1 ? "dictionary_row_open" : "dictionary_row_close",
+                "div",
+                nesting,
+            );
+            token.block = true;
+            output.push(token);
+        };
+        for (const token of state.tokens) {
+            if (token.type === "dl_open") {
+                if (!(token.attrGet("class") ?? "").split(/\s+/).includes("dictionary"))
+                    token.attrJoin("class", "dictionary");
+                lists.push({ row: false });
+            } else if (token.type === "dt_open" && lists.length) {
+                const list = lists.at(-1);
+                if (list.row) row(-1);
+                row(1);
+                list.row = true;
+            } else if (token.type === "dd_open" && lists.length) {
+                // A loose definition begins with an inline first paragraph.
+                token.block = false;
+            } else if (token.type === "dt_close" && lists.length) {
+                // Inter-tag whitespace would add a word space to the fixed gap.
+                token.block = false;
+            } else if (token.type === "dl_close" && lists.length) {
+                if (lists.pop().row) row(-1);
+            }
+            output.push(token);
+        }
+        state.tokens = output;
+    });
+}

package/engine/frontmatter-lint.mjs

@@ -1143,6 +1143,7 @@ function checkEmbeddedShortcodes(note, blockName) {
  * @param {object} note - A note from the link index (`{fm, file, raw, type}`).
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @param {string} [opts.currentDate="720.1"] - Setting-wide neutral date for age checks.
  * @param {object} [opts.index] - The link index, for the reference check, which
  *   runs through its `shortcodeHit`. Its absence skips that check rather than
  *   reporting every reference as dead.
@@ -1175,6 +1176,7 @@ export function lintNote(
     {
         schemas,
         index,
+        currentDate,
         vocabulary,
         packs,
         emittedArt,
@@ -1544,7 +1546,8 @@ export function lintNote(
             findings.push(...field.check(note, { index, addressContext: referenceContext }));
         }
         // A check the type declares of the whole note, with the same index.
-        if (typeof entry.check === "function") findings.push(...entry.check(note, { index }));
+        if (typeof entry.check === "function")
+            findings.push(...entry.check(note, { index, currentDate }));
     }
 
     const fields = authoredFields(schema);
@@ -1717,6 +1720,7 @@ export function lintNote(
  * @param {object} index - From `buildLinkIndex`.
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @param {string} [opts.currentDate="720.1"] - Setting-wide neutral date for age checks.
  * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
  *   it declares; see {@link lintNote}.
  * @param {boolean} [opts.references=true] - Whether to check references.
@@ -1732,7 +1736,7 @@ export function lintNote(
  */
 export function lintFrontmatter(
     index,
-    { schemas, vocabulary, packs, emittedArt, references = true, systems },
+    { schemas, vocabulary, packs, emittedArt, references = true, systems, currentDate },
 ) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
@@ -1745,6 +1749,7 @@ export function lintFrontmatter(
             ...lintNote(note, {
                 schemas,
                 vocabulary,
+                currentDate,
                 packs,
                 emittedArt,
                 index: references ? index : undefined,

package/engine/helpers.mjs

@@ -41,6 +41,7 @@ import unidecode from "unidecode";
 import markdownit from "markdown-it";
 import footnotePlugin from "markdown-it-footnote";
 import deflistPlugin from "markdown-it-deflist";
+import { dictionaryListPlugin } from "./definition-list.mjs";
 import { iconPlugin } from "./content-icons.mjs";
 import { imagePlugin, imagesIn } from "./content-images.mjs";
 import { embedRole, resolveEmbeds } from "./content-embeds.mjs";
@@ -108,6 +109,7 @@ let localAssetImageInfoCache;
 export const md = markdownit({ html: true })
     .use(footnotePlugin)
     .use(deflistPlugin)
+    .use(dictionaryListPlugin)
     .use(spanMarkdownPlugin, { spoilers: true })
     .use(dictionaryEntryPlugin)
     // A heading's attribute block, written onto the heading element rather than

package/engine/index.mjs

@@ -155,6 +155,8 @@ export * as calendarNotes from "./calendar-notes.mjs";
 export * as calendarArtifacts from "./calendar-artifacts.mjs";
 
 /** A being's `age`, absent beside a dated `born`: the age the date computes to. */
+export * as definitionList from "./definition-list.mjs";
+export * as currentDate from "./current-date.mjs";
 export * as beingAge from "./being-age.mjs";
 
 /** The one normalisation this build makes: prose to a URL-safe token. */

package/engine/infobox.mjs

@@ -1038,11 +1038,7 @@ function noteBox(
         // A culture note resolves to itself, and a row linking it to itself
         // says nothing.
         if (field.name === "culture" && cultureNamesItself(fm, raw, { contentPackage })) continue;
-        if (
-            ((fm?.type === "being" && ["born", "died"].includes(field.name)) ||
-                (fm?.type === "place" && field.name === "present")) &&
-            dates
-        ) {
+        if (fm?.type === "being" && ["born", "died"].includes(field.name) && dates) {
             const parsed = parseNoteDate(raw, dates).date;
             const era =
                 parsed?.marker ? dates.markers?.get(parsed.marker)

package/engine/note-vocabulary.mjs

@@ -92,7 +92,7 @@ import {
     checkWorldFacts,
 } from "./calendar-notes.mjs";
 // Whether a being's authored `age` disagrees with what `born` and the
-// package's declared present compute — the closed `data:` container's own
+// configured current date compute — the closed `data:` container's own
 // question, asked the way `checkPlace` and `checkCalendarNote` are.
 import { checkBeingAge } from "./being-age.mjs";
 import { checkSocialTies } from "./social-ties.mjs";
@@ -1522,7 +1522,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         stubbable: true,
         subTypes: Object.freeze(["npc", "character", "creature"]),
         // Whether an authored `age` disagrees with what `born` and the
-        // package's declared present compute — see `engine/being-age.mjs`.
+        // configured current date compute — see `engine/being-age.mjs`.
         check: checkBeingAge,
         data: Object.freeze([
             TOKEN_ICON,

package/engine/npc-generate.mjs

@@ -44,9 +44,8 @@
  *   `complexion` is a list of the one word drawn.
  * - `height` — from the profile's range for the gender, in feet and inches.
  * - `weight` — from the height and the frame's body-mass band, in pounds.
- * - `born` — an adult age of {@link ADULT_AGE} years before the package's
- *   present, as a neutral `<year>.<day>` date. A package that states no present
- *   gets `born: unknown`.
+ * - `born` — an adult age of {@link ADULT_AGE} years before the configured
+ *   current date, as a neutral `<year>.<day>` date. The default is `720.1`.
  * - `archetypes: [commoner]`, the archetype for a person who fits no more
  *   specific one.
  * - `icon`, `species` and `packFolder` — what the caller derives from the
@@ -55,7 +54,7 @@
  *   are `[]`; `affiliations` is `{}`; `appearance.extra_features` is `[]`.
  *
  * Plain ESM with no filesystem access; the CLI resolves the culture, its
- * language's name lists and the present and hands them in.
+ * language's name lists and the configured current date and hands them in.
  *
  * @module
  */
@@ -65,6 +64,7 @@ import YAML from "yaml";
 import { BEING_LOOK_VOCABULARY } from "./note-vocabulary.mjs";
 import { FRAME_MASS_INDEX, profileLookKeys } from "./appearance-profile.mjs";
 import { parseBeingHeight } from "./being-measurements.mjs";
+import { normalizeCurrentDate } from "./current-date.mjs";
 import { computeAge, parseAgeMagnitude } from "./being-age.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
 import { eraYear } from "./calendars.mjs";
@@ -435,7 +435,7 @@ function frontmatterYaml(frontmatter) {
  *   about a name that does not fit.
  * @param {string} [context.seed] - Text joined to the spec's own seed, to draw a
  *   different person from the same spec.
- * @param {unknown} [context.present] - The package's present, or `null`.
+ * @param {unknown} [context.currentDate] - The setting's neutral current date, defaulting to "720.1".
  * @param {object} [context.dateContext] - The reckoning context the present
  *   and `born` are read in, with `daysPerYear`.
  * @param {{icon?: unknown, species?: unknown, packFolder?: unknown}} [context.defaults] -
@@ -449,7 +449,8 @@ function frontmatterYaml(frontmatter) {
 export function generateNpc(spec, context) {
     const problems = npcSpecProblems(spec);
     if (problems.length) throw new Error(problems.join("; "));
-    const { profile, names, present = null, dateContext = {}, defaults = {} } = context;
+    const { profile, names, currentDate, dateContext = {}, defaults = {} } = context;
+    const present = normalizeCurrentDate(currentDate);
     if (!isPlainMap(names)) throw new Error("`npc new` needs the language's `data.names`");
     const taken = context.taken ?? new Set();
     const seed = canonicalSpec(spec) + (given(context.seed) ? `\u0000${context.seed}` : "");

package/engine/pdf-render.mjs

@@ -822,9 +822,9 @@ function renderBlock(tokens, i, out, ctx) {
                     definitions.push(renderTokens(tokens.slice(at + 1, definitionEnd), ctx));
                     at = definitionEnd + 1;
                 }
-                entries.push(`terms.item([${term}],[${definitions.join("\n\n")}])`);
+                entries.push(`book-definition([${term}],[${definitions.join("\n\n")}])`);
             }
-            out.push(`\n#terms(${entries.join(", ")})\n\n`);
+            out.push(`\n${renderDefinitionList(entries)}\n\n`);
             return end - i + 1;
         }
         case "table_open": {
@@ -840,6 +840,36 @@ function renderBlock(tokens, i, out, ctx) {
     }
 }
 
+/**
+ * Self-contained dictionary rows with the website's 150 CSS-pixel hanging indent.
+ *
+ * Each row remains a breakable block; only the bold term is an inline box. The
+ * negative first-line space lets its label start at the original margin while
+ * subsequent paragraphs, lists and blocks retain the definition's inset. A long
+ * term enlarges its slot without changing the continuation margin.
+ *
+ * Scope the helper to this list so exported Markdown fragments also work without
+ * a book preamble, including nested definition lists.
+ * @param {string[]} entries - Calls containing already-rendered terms and bodies.
+ * @returns {string} Typst markup.
+ */
+function renderDefinitionList(entries) {
+    return `#context {
+  let book-definition(term, body) = {
+    let indent = 112.5pt
+    let gap = (0.75em).to-absolute()
+    let label = text(weight: "bold", term)
+    let slot = calc.max(indent - gap, measure(label).width)
+    block(width: 100%, breakable: true, inset: (left: indent), above: 0pt, below: 0.5em)[
+      #set par(first-line-indent: 0pt, hanging-indent: 0pt)
+      #set text(weight: "regular")
+      #h(-indent)#box(width: slot, label)#h(gap)#body
+    ]
+  }
+  ${entries.join("\n  ")}
+}`;
+}
+
 /**
  * A withheld section, set in the box a `secret` block is set in.
  *
@@ -1210,7 +1240,10 @@ function renderInline(token, ctx) {
                 out.push(inlineRaw(child.content));
                 break;
             case "span_open": {
-                const classes = (child.attrGet?.("class") ?? "").split(/\s+/).filter(Boolean);
+                // Inline secrecy has no print presentation; other classes and ids survive.
+                const classes = (child.attrGet?.("class") ?? "")
+                    .split(/\s+/)
+                    .filter((value) => value && value !== "secret");
                 const values = classes
                     .map((value) => '"' + escapeTypstString(value) + '"')
                     .join(", ");
@@ -1630,7 +1663,7 @@ export function bookTypstPreamble() {
         // weight so it remains bold inside an ordinary strong phrase.
         "#let book-span(body, classes: ()) = {\n" +
             '  let styled = if classes.contains("name") { text(weight: "bold", body) } else { body }\n' +
-            '  if classes.contains("secret") { box(fill: rgb("#f2eefb"), inset: (x: 3pt, y: 1pt), text(fill: rgb("#5c4b8a"))[#strong[Secret:] #styled]) } else { box(styled) }\n' +
+            "  box(styled)\n" +
             "}",
         // Use the file's natural measure for auto. Every requested width is
         // bounded by the available measure and by the height of a page.

package/engine/preview-current-date.mjs

@@ -0,0 +1,60 @@
+/*
+ * 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
+ */
+
+/** Opt-in date configuration for preview hosts; no content or dependency reads. @module */
+import fs from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import YAML from "yaml";
+import { findConfigFile } from "./pack-config.mjs";
+import { formatDiagnostic, positionOfYamlPath } from "./diagnostics.mjs";
+import { normalizeCurrentDate } from "./current-date.mjs";
+
+/**
+ * Read only currentDate from the nearest package configuration.
+ * YAML does not load the full build configuration. An MJS configuration executes
+ * its own module, as any caller opting into a code configuration expects.
+ * @param {string} root - Directory at which configuration discovery starts.
+ * @returns {Promise<string>} Validated neutral current date.
+ */
+export async function readPreviewCurrentDate(root) {
+    const file = findConfigFile(root);
+    if (!file) return normalizeCurrentDate();
+    let source = "";
+    try {
+        let input;
+        if (file.endsWith(".mjs")) {
+            const version = (await fs.stat(file)).mtimeMs;
+            const module = await import(`${pathToFileURL(file).href}?previewDate=${version}`);
+            input = module.default ?? module;
+        } else {
+            source = await fs.readFile(file, "utf8");
+            const document = YAML.parseDocument(source);
+            if (document.errors.length) throw document.errors[0];
+            input = document.toJS();
+        }
+        if (!input || typeof input !== "object" || Array.isArray(input)) {
+            throw new TypeError("package configuration must be a mapping");
+        }
+        return normalizeCurrentDate(input.currentDate);
+    } catch (error) {
+        throw new Error(
+            formatDiagnostic({
+                file,
+                ...(source ? positionOfYamlPath(source, ["currentDate"]) : {}),
+                severity: "error",
+                message: error.message,
+            }),
+            { cause: error },
+        );
+    }
+}

package/engine/site-build.mjs

@@ -91,7 +91,8 @@ import { searchableFrontmatter } from "./note-package.mjs";
 import { indexRecordsFor } from "./content-index.mjs";
 // A being's computed `age` — see `engine/being-age.mjs`. `pdf-build.mjs`
 // reuses `collectContentPages`'s pages, so wiring it here reaches the book too.
-import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
+import { applyComputedBeingAge } from "./being-age.mjs";
+import { normalizeCurrentDate } from "./current-date.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { resolvedDateFields } from "./note-dates.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
@@ -213,9 +214,7 @@ export function collectContentPages(contentBase, ctx) {
     const addressFindings = [];
     const fmLinkFindings = [];
 
-    // The package's declared present, read once from the same corpus the site
-    // and the PDF share — see `engine/being-age.mjs`. `pdf-build.mjs` reaches
-    // this through the pages this function returns, so one call covers both.
+    // Site and PDF pages use the setting date alongside shared calendar context.
     const records =
         ctx.records ??
         indexRecordsFor({
@@ -223,7 +222,7 @@ export function collectContentPages(contentBase, ctx) {
             config: ctx.config,
             skipDirectories: ctx.skipDirectories,
         });
-    const present = presentAmongRecords(records);
+    const present = normalizeCurrentDate(ctx.config?.currentDate);
     const dates = reckoningContext({ notes: records });
 
     for (const file of siteCorpusFiles(contentBase, ctx)) {
@@ -479,6 +478,7 @@ export function siteGates(pages, findings, { config, records, sqlTables }) {
         :   pages;
     out.index = buildSiteIndex(expanded, {
         package: config.contentPackage,
+        currentDate: config.currentDate,
         foreignIndex: foreign.index,
         foreignReferences: foreign.references,
         records,

package/engine/site-index.mjs

@@ -68,7 +68,7 @@ import {
 import { NOTE_SYSTEM } from "./systems.mjs";
 import { contentPackage } from "./content-package.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
-import { presentAmongRecords } from "./being-age.mjs";
+import { normalizeCurrentDate } from "./current-date.mjs";
 // The declared tag vocabulary, which is where `draft` is stated.
 import { isGmNote, isDraftNote } from "./note-vocabulary.mjs";
 
@@ -165,6 +165,8 @@ function mergeForeign(index, foreignIndex) {
  * @param {readonly SiteEntry[]} entries - Every page the site will publish,
  *   each already knowing its own `url`.
  * @param {object} [options] - Cross-package inputs.
+ * @param {string} [options.package] - The builder's own content package.
+ * @param {string} [options.currentDate="720.1"] - Setting-wide neutral date for recurring events.
  * @param {Map<string, {package: string, type?: string}>} [options.foreignIndex]
  *   The merged index from `loadForeignIndexes`. Omit when the build publishes
  *   no cross-package links.
@@ -183,6 +185,7 @@ export function buildSiteIndex(
         foreignIndex = new Map(),
         noIndexPackages = new Set(),
         package: builderPackage,
+        currentDate,
         records = [],
         foreignReferences = new Map(),
         syntax,
@@ -303,7 +306,7 @@ export function buildSiteIndex(
         // event's `next` is computed against this present.
         dateContext: {
             ...reckoningContext({ notes: records }),
-            present: presentAmongRecords(records),
+            present: normalizeCurrentDate(currentDate),
         },
         referenceTargets: buildReferenceTargets(records, new Map([...foreignReferences, ...index])),
         index,