@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/homepage.mjs

@@ -131,12 +131,12 @@ export function isHomepage(fm) {
  * `name` and `shortcode` are permitted: the shortcode is what a link is
  * written with, and `name` titles the page like every other note's.
  *
- * **A named class, not an allow-list, and that boundary is the decision.** A
- * homepage's frontmatter is *emitted into the published page*
- * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
- * parameter this build has never heard of and has no standing to refuse.
- * Rejecting unknown keys would make every new theme parameter wait on a
- * package-build release.
+ * **A named class, not an allow-list, and that boundary is the decision.**
+ * What this class answers is a key the top-level vocabulary *accepts* and a
+ * homepage still cannot use, which is a different question from an unknown
+ * key: the frontmatter lint refuses those for every note alike, naming the
+ * closed vocabulary, so repeating that judgement per type would be a second
+ * answer to one question.
  *
  * `aliases` is deliberately not in the class: it is a **retired** field, refused
  * on every note whatever its type, so it is answered there rather than
@@ -340,7 +340,7 @@ function positionOfType(file) {
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
  * authored `name.full` wins, because a front page may greet a reader
- * differently from a package browser. A top-level `title` is also readable.
+ * differently from a package browser.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.
@@ -350,7 +350,7 @@ function positionOfType(file) {
  * @returns {string} The title.
  */
 export function homepageTitle(fm, config) {
-    const authored = fm?.name?.full ?? fm?.title;
+    const authored = fm?.name?.full;
     if (typeof authored === "string" && authored.trim()) return authored;
     const manifest = /** @type {Record<string, unknown>|undefined} */ (
         config?.packageBuild?.manifest

package/engine/index.mjs

@@ -220,6 +220,9 @@ export * as contentHtml from "./content-html.mjs";
 /** An image saying how wide it is and where it sits, in two closed vocabularies. */
 export * as contentImages from "./content-images.mjs";
 
+/** A list item opened with `[ ]` or `[x]`, which every surface reads as text. */
+export * as contentTaskLists from "./content-tasklists.mjs";
+
 /** `![[…]]` — the wikilink that renders a picture where it stands. */
 export * as contentEmbeds from "./content-embeds.mjs";
 

package/engine/infobox-render.mjs

@@ -36,7 +36,7 @@
 
 import { encodeAddresses } from "./address-values.mjs";
 import { sectionHolds } from "./infobox.mjs";
-import { escapeTypst, escapeTypstString } from "./pdf-render.mjs";
+import { absolutePageUrl, escapeTypst, escapeTypstString } from "./pdf-render.mjs";
 
 /**
  * How many cells an attribute grid packs into a row.
@@ -139,7 +139,12 @@ function sectionToHtml(section, link) {
     if (section.layout === "rows") {
         out.push('<dl class="infobox-rows">');
         for (const row of section.rows ?? []) {
-            out.push(`<dt>${escapeHtml(row.label)}</dt><dd>${valueToHtml(row, link)}</dd>`);
+            // A row that declares an anchor carries it on the `<dt>`, so the
+            // label is the destination a link to that row arrives at. A row
+            // that declares none emits none: an id nobody wrote would be
+            // invented once per renderer, and the two would not agree.
+            const id = row.id ? ` id="${escapeHtml(row.id)}"` : "";
+            out.push(`<dt${id}>${escapeHtml(row.label)}</dt><dd>${valueToHtml(row, link)}</dd>`);
         }
         out.push("</dl>");
     } else if (section.layout === "grid") {
@@ -221,16 +226,22 @@ export function sectionHasContent(section) {
  * reference, so the link works on paper as a cross-reference and in a PDF
  * viewer as a jump. Everything else is set as its own words.
  *
+ * A panel's rows address pages the same way prose does, so a page the book does
+ * not print is set as the absolute URL a reader can follow — see
+ * {@link module:engine/pdf-render.absolutePageUrl}.
+ *
  * @param {object} value - A `link` value.
  * @param {Map<string, string>} links - Address slug → the book's anchor.
  * @param {(anchor: string) => string} labelFor - The anchor's Typst label.
+ * @param {string} [site] - The absolute address this book's pages are served at.
  * @returns {string} Typst markup.
  */
-export function linkToTypst(value, links, labelFor) {
+export function linkToTypst(value, links, labelFor, site) {
     const text = escapeTypst(value?.text ?? "");
     const anchor = value?.address ? links?.get(encodeAddresses(value.address)) : undefined;
     if (anchor) return `#link(<${labelFor(anchor)}>)[${text}]`;
-    if (value?.url) return `#link("${escapeTypstString(value.url)}")[${text}]`;
+    if (value?.url)
+        return `#link("${escapeTypstString(absolutePageUrl(value.url, site))}")[${text}]`;
     return text;
 }
 
@@ -370,7 +381,13 @@ export function infoboxTypstPreamble() {
             "fill: infobox-rule)[#upper(t)]; v(0.20em) }",
         '#let infobox-head(t) = { v(0.40em); text(size: 7.6pt, weight: "bold", ' +
             "tracking: 1.3pt, fill: infobox-rule)[#upper(t)]; v(0.16em) }",
+        // One definition-list style across the three surfaces: the term right
+        // against a fixed column so every term in the panel shares one edge,
+        // and space below the row rather than rows run together. A page has one
+        // width, so the stacked state the screen surfaces fall back to has
+        // nothing to answer here and is not drawn.
         "#let infobox-row(k, v) = grid(columns: (2.05cm, 1fr), column-gutter: 4pt, " +
+            "inset: (bottom: 2pt), align: (right + top, left + top), " +
             "text(size: 7pt, tracking: 0.5pt, fill: infobox-faint)[#upper(k)], text(size: 8pt)[#v])",
         "#let infobox-cell(lab, val) = align(center)[" +
             "#text(size: 7pt, tracking: 0.6pt, fill: infobox-faint)[#lab]#h(2.5pt)" +

package/engine/infobox.mjs

@@ -121,6 +121,13 @@ import { subtypeRow } from "./document-subtypes.mjs";
 import { authoredKey } from "./system-block.mjs";
 import { formatDateInCalendar, formatNoteDate, parseNoteDate } from "./note-dates.mjs";
 import { displayBeingHeight, displayBeingWeight } from "./being-measurements.mjs";
+import {
+    officeAnchor,
+    officeRoster,
+    rankAnchor,
+    readStandings,
+    standingPhrase,
+} from "./standings.mjs";
 
 /**
  * How a section arranges what it holds.
@@ -326,7 +333,8 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
     }),
     "being.appearance.complexion": Object.freeze({
         group: "appearance",
-        phrase: (v) => `${humanizeValue(v)} complexion`,
+        whole: true,
+        phrase: (v) => `${humanizedList(v)} complexion`,
     }),
     "being.appearance.extra_features": Object.freeze({ group: "appearance" }),
 });
@@ -468,6 +476,24 @@ export function humanizeValue(value) {
         .trim();
 }
 
+/**
+ * Several enumerated values as one clause — `weathered, ruddy and scarred`.
+ *
+ * A field that admits one value or a list of them reads as a single phrase, so
+ * the noun it qualifies is said once rather than once per value. Internal: the
+ * phrase that wants it is declared in this module.
+ *
+ * @param {unknown} value - One value, or a list of them.
+ * @returns {string} The text.
+ */
+function humanizedList(value) {
+    const parts = (Array.isArray(value) ? value : [value])
+        .filter((entry) => entry !== undefined && entry !== null && entry !== "")
+        .map((entry) => humanizeValue(entry));
+    if (parts.length < 2) return parts[0] ?? "";
+    return `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`;
+}
+
 /**
  * A value as a row shows it.
  *
@@ -553,11 +579,143 @@ function rowValue(kind, raw, resolve, hint) {
     return presentValue(raw);
 }
 
+/**
+ * A being's memberships, each with the standing it holds there.
+ *
+ * One row, one entry per body, and the standing reads inside the entry rather
+ * than beside it — "War Chief, of Vrystwald Tribes" rather than a rank link
+ * with nothing saying which body confers it.
+ *
+ * **The office carries the link where the body's page anchors it.** An office's
+ * description is already declared in the body's own `governance.offices`, and
+ * the row that prints it is anchored by the same derivation, so the string a
+ * being wrote reaches the description without anyone authoring a note about the
+ * post. In a medium with no page to reach — a compendium journal links by
+ * document UUID — the entry keeps the body's own document, so the reader still
+ * lands somewhere.
+ *
+ * @param {object} field - The declaration.
+ * @param {unknown} raw - The authored value, in either form.
+ * @param {(ref: unknown, hint?: object) => object|undefined} resolve - The
+ *   medium's resolver.
+ * @param {string} label - The row's label.
+ * @returns {object[]} The row, or none where nothing is held.
+ */
+function standingRows(field, raw, resolve, label) {
+    const { entries } = readStandings(raw);
+    const value = [];
+    for (const { body, standing } of entries) {
+        if (!hasValue(body)) continue;
+        const link = linkValue(body, resolve, { type: field.ref });
+        const digest = resolve?.(body, { type: field.ref })?.standings;
+        const text = standingPhrase(standing, link.text, digest);
+        const anchor =
+            (
+                typeof standing?.office === "string" &&
+                digest?.offices?.[standing.office] !== undefined
+            ) ?
+                officeAnchor(standing.office)
+            :   "";
+        value.push({
+            ...link,
+            text,
+            ...(anchor && link.url ? { url: `${link.url}#${anchor}` } : {}),
+        });
+    }
+    return value.length ? [{ label, kind: "links", value }] : [];
+}
+
+/**
+ * A map of named posts, one row each, anchored by its name.
+ *
+ * The **name is the label and its description is the value**, which is the way
+ * round a reader needs: a field name belongs in the label column, and a whole
+ * sentence there leaves the post itself standing where a value goes.
+ *
+ * Each row carries the anchor its name derives, so the description is a
+ * destination rather than merely text on a page — which is what lets a being's
+ * `office` string link to the post it names without anyone authoring a note
+ * about the post.
+ *
+ * @param {unknown} raw - The authored map.
+ * @returns {object[]|null} One row per post, in the order the body declared
+ *   them, or `null` where the value is not a map of them — a note writing
+ *   something else keeps its row and states what it wrote.
+ */
+function rosterRows(raw) {
+    if (!isMapping(raw) || isAddressTuple(raw)) return null;
+    const rows = [];
+    for (const [post, description] of officeRoster(raw)) {
+        if (!hasValue(post)) continue;
+        const anchor = officeAnchor(post);
+        rows.push({
+            ...(anchor ? { id: anchor } : {}),
+            label: String(post),
+            kind: "text",
+            value: hasValue(description) ? String(description) : String(post),
+        });
+    }
+    return rows;
+}
+
+/**
+ * A ladder of named ranks, one row each, ordered by the level a body confers.
+ *
+ * The **title is the label and its description is the value**, the same
+ * convention {@link rosterRows} draws a body's offices with, so a reader
+ * meets the two lists the same way. A rung's optional `lore` — already
+ * resolved to an Address by the time this runs — reads alongside the
+ * description rather than replacing it, since the description is what the
+ * rung itself states and the lore is a pointer to more.
+ *
+ * @param {unknown} raw - The authored `governance.ranks` list.
+ * @param {(ref: unknown, hint?: object) => object|undefined} resolve - The
+ *   medium's resolver.
+ * @returns {object[]|null} One row per rung, in ascending level, or `null`
+ *   where the value is not a list of them.
+ */
+function rankRows(raw, resolve) {
+    if (!Array.isArray(raw)) return null;
+    const rungs = raw
+        .filter((rung) => isMapping(rung) && hasValue(rung.title))
+        .toSorted((a, b) => Number(a.level ?? 0) - Number(b.level ?? 0));
+    const rows = [];
+    for (const rung of rungs) {
+        const anchor = rankAnchor(String(rung.title));
+        const description =
+            hasValue(rung.description) ? String(rung.description) : String(rung.title);
+        const lore = hasValue(rung.lore) ? linkValue(rung.lore, resolve, { type: "lore" }) : null;
+        rows.push({
+            ...(anchor ? { id: anchor } : {}),
+            label: String(rung.title),
+            kind: "text",
+            value: lore?.text ? `${description} (Lore: ${lore.text})` : description,
+        });
+    }
+    return rows;
+}
+
 /** Expand structured references using the existing linked-row shape. */
 function structuredRows(field, raw, resolve, label, fm) {
-    if (Array.isArray(raw) && raw.some(isMapping)) {
-        const links = raw
-            .filter((entry) => isMapping(entry) && hasValue(entry.to))
+    if (field.standings) return standingRows(field, raw, resolve, label);
+    if (field.roster) {
+        const roster = rosterRows(raw);
+        if (roster) return roster;
+    }
+    if (field.ranks) {
+        const ranks = rankRows(raw, resolve);
+        if (ranks) return ranks;
+    }
+    // A relationship entry — `{to, ...}` — is a mapping that is not itself an
+    // Address: an authored plain list of addresses normalises to a list of
+    // Address tuples, which `isMapping` also reports true for, and treating
+    // one as a relationship keyed off a `to` it never carries is what emptied
+    // `lore`, `parents`, `domains` and `economy` silently.
+    const relations =
+        Array.isArray(raw) ? raw.filter((entry) => isMapping(entry) && !isAddressTuple(entry)) : [];
+    if (relations.length) {
+        const links = relations
+            .filter((entry) => hasValue(entry.to))
             .map((entry) => {
                 const link = linkValue(entry.to, resolve, { type: field.ref ?? "place" });
                 const details = Object.entries(entry)
@@ -581,7 +739,7 @@ function structuredRows(field, raw, resolve, label, fm) {
                 const address = parseAddress(
                     target,
                     {
-                        package: fm.package ?? "local",
+                        package: "local",
                         system: "note",
                         types: new Set(field.accepts),
                     },
@@ -704,7 +862,7 @@ function noteBox(
     const rows = [];
     /** @type {Set<string>} */
     const shown = new Set();
-    const name = fm?.name?.full ?? fm?.title;
+    const name = fm?.name?.full;
     if (hasValue(name)) rows.push({ label: "Name", kind: "text", value: String(name) });
     if (Array.isArray(fm?.name?.aliases) && fm.name.aliases.length) {
         rows.push({ label: "Aliases", kind: "list", value: fm.name.aliases });
@@ -772,7 +930,9 @@ function noteBox(
                 label: GROUP_LABELS[overlay.group] ?? humanizeFieldName(overlay.group),
                 entries: [],
             };
-            const parts = Array.isArray(raw) ? raw.filter(hasValue) : [raw];
+            // A `whole` phrase reads the value entire, so several values compose
+            // into one clause rather than repeating the noun once each.
+            const parts = overlay.whole || !Array.isArray(raw) ? [raw] : raw.filter(hasValue);
             for (const part of parts) {
                 group.entries.push(overlay.phrase ? overlay.phrase(part) : humanizeValue(part));
             }

package/engine/journals.mjs

@@ -71,6 +71,14 @@ import { journalHasContent } from "./note-state.mjs";
 import { draftNoticeFor } from "./draft-notice.mjs";
 import { scanCaptions } from "./content-captions.mjs";
 import { separateFootnotes } from "./content-footnotes.mjs";
+import { WITHHELD_CLASS, pageOpenings } from "./heading-attributes.mjs";
+
+/**
+ * `CONST.DOCUMENT_OWNERSHIP_LEVELS.NONE` — the default ownership a withheld
+ * page states. A GM reads every document whatever it says; everyone else reads
+ * this one not at all.
+ */
+const WITHHELD_OWNERSHIP = 0;
 
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
@@ -78,7 +86,8 @@ import { separateFootnotes } from "./content-footnotes.mjs";
  * a split. Content before the first H1 (if non-empty) becomes a leading
  * page. Each H1 yields a page whose name is the heading
  * text (with any `{#anchor-id}` suffix stripped out and surfaced as
- * `anchorSlug`).
+ * `anchorSlug`). The classes the heading declares come along as `classes`, so
+ * a surface that honours one has it without reading the suffix again.
  *
  * `leadName` names that leading page. A journal note's is "Introduction",
  * because it introduces the pages that follow. An item doc's is the item — a
@@ -89,7 +98,7 @@ import { separateFootnotes } from "./content-footnotes.mjs";
  * @param {string} body - Markdown body to split.
  * @param {string} [leadName] - Name of the page before the first heading.
  * @returns {Array<{name: string, anchorSlug: string|null, level: number,
- *   markdown: string}>} Pages in document order.
+ *   classes: string[], markdown: string}>} Pages in document order.
  */
 export function splitPages(body, leadName = "Introduction") {
     const { markdown, definitions } = separateFootnotes(body);
@@ -101,6 +110,7 @@ export function splitPages(body, leadName = "Introduction") {
             .filter((caption) => /^\s*#{1,6}\s/.test(lines[caption.blockStart] ?? ""))
             .map((caption) => caption.blockStart),
     );
+    const openings = pageOpenings(markdown);
     const pages = [];
     const beforeFirstH1 = [];
     let current = null;
@@ -113,6 +123,7 @@ export function splitPages(body, leadName = "Introduction") {
             name: current.name,
             anchorSlug: current.anchorSlug,
             level: current.level,
+            classes: current.classes,
             markdown: current.lines.join("\n").trim(),
         });
         current = null;
@@ -128,11 +139,13 @@ export function splitPages(body, leadName = "Introduction") {
         // An H1 starts a page, as does any heading carrying an `{#slug}`
         // anchor: a Foundry UUID can only address a page, so a linkable
         // section has to be one.
-        const headingMatch =
-            !inCodeBlock && !inSecret ? line.match(/^\s*(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
-        const rawHeading = headingMatch?.[2]?.trim();
-        const anchorMatch = rawHeading?.match(/^(.*?)\s*\{#([^}]+)\}\s*$/);
-        const startsPage = headingMatch && (headingMatch[1].length === 1 || anchorMatch);
+        // {@link module:engine/heading-attributes.parseHeadingLine} is the one
+        // reading of that rule — `scanBlocks` and `scanCaptions` refuse such a
+        // heading written where it cannot become a page, from the same
+        // function, so none of them can disagree about what starts one. The
+        // lines it claims here are collected by `pageOpenings`, which also
+        // skips a fence and a named block.
+        const opening = openings.get(lineIndex);
         const caption = !inCodeBlock && !inSecret ? captionStarts.get(lineIndex) : null;
         if (caption) {
             closeCurrent();
@@ -140,16 +153,18 @@ export function splitPages(body, leadName = "Introduction") {
                 name: caption.label,
                 anchorSlug: caption.id,
                 level: 1,
+                classes: [],
                 lines: [line],
             };
             continue;
         }
-        if (startsPage && !captionedHeadings.has(lineIndex)) {
+        if (opening && !captionedHeadings.has(lineIndex)) {
             closeCurrent();
             current = {
-                name: (anchorMatch ? anchorMatch[1] : rawHeading).trim(),
-                anchorSlug: anchorMatch?.[2]?.trim() || null,
-                level: headingMatch[1].length,
+                name: opening.text,
+                anchorSlug: opening.id || null,
+                level: opening.level,
+                classes: opening.classes,
                 lines: [],
             };
             continue;
@@ -169,6 +184,7 @@ export function splitPages(body, leadName = "Introduction") {
             name: leadName,
             anchorSlug: null,
             level: 1,
+            classes: [],
             markdown: intro,
         });
     }
@@ -273,10 +289,14 @@ export function journalPageId(entryId, page) {
  * @param {Array<object>} rawPages - From {@link splitPages}.
  * @param {string} entryId - The owning JournalEntry's `_id`.
  * @param {string} noteName - The note, for error messages.
+ * A page whose heading carries `.secret` is given to the GM alone, by the one
+ * ownership value Foundry reads as "nobody but a GM". Every other page states
+ * no ownership and inherits the journal's.
+ *
  * @returns {Array<{_id: string, name: string, type: string,
  *   title: {show: boolean, level: number},
- *   text: {format: number, content: string}, _key: string}>} The page
- *   documents, in order.
+ *   text: {format: number, content: string}, _key: string,
+ *   ownership?: {default: number}}>} The page documents, in order.
  * @throws {Error} When the note has no content at all, or repeats an anchor.
  */
 export function buildPages(rawPages, entryId, noteName, captions) {
@@ -296,6 +316,7 @@ export function buildPages(rawPages, entryId, noteName, captions) {
     }
     return rawPages.map((page) => {
         const pageId = journalPageId(entryId, page);
+        const withheld = (page.classes ?? []).includes(WITHHELD_CLASS);
         return {
             _id: pageId,
             name: page.name,
@@ -308,6 +329,7 @@ export function buildPages(rawPages, entryId, noteName, captions) {
                         renderFoundryMarkdown(page.markdown, captions, footnoteNumbers, pageId)
                     :   "",
             },
+            ...(withheld ? { ownership: { default: WITHHELD_OWNERSHIP } } : {}),
             _key: `!journal.pages!${entryId}.${pageId}`,
         };
     });
@@ -329,7 +351,6 @@ export function buildPages(rawPages, entryId, noteName, captions) {
  * @param {string} [params.leadName] - Name for the page before the first
  *   heading; see {@link splitPages}.
  * @param {string|null} [params.folder] - The folder id, or `null`.
- * @param {object} [params.flags] - Document flags.
  * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
  *   caller because it is a property of the *pack* being written, not of the
  *   entry: a module may ship the same content for two systems, and each pack's
@@ -352,7 +373,6 @@ export function buildJournalEntry({
     markdown,
     leadName,
     folder = null,
-    flags,
     stats = defaultStats(),
     infoboxes = [],
     notice = "",
@@ -379,7 +399,7 @@ export function buildJournalEntry({
         folder,
         sort: 0,
         ownership: { default: 0 },
-        flags: flags || {},
+        flags: {},
         _id: id,
         _stats: stats,
         _key: `!journal!${id}`,
@@ -546,7 +566,6 @@ export class Journals extends BasePackCompiler {
             // "Introduction" — see {@link splitPages}.
             leadName: ownsDoc ? name : undefined,
             folder,
-            flags: fm.flags,
             stats: this.stats,
         });
     }

package/engine/macros.mjs

@@ -272,7 +272,7 @@ export function buildMacroEntry(fm, { command, folder = null, stats = defaultSta
         folder,
         sort: 0,
         ownership: { default: 0 },
-        flags: fm.flags || {},
+        flags: {},
         _id: id,
         _stats: stats,
         _key: `!macros!${id}`,