@heroiclands/package-build 21.0.0 → 21.2.0

package/engine/pathnames.mjs

@@ -93,6 +93,8 @@
  * @module
  */
 
+import { PACKAGEBUILD_PACKAGE } from "./packages.mjs";
+
 /**
  * The directory a package ships its files in, and the segment that marks a
  * pathname's first segment as a package name.
@@ -220,6 +222,78 @@ export function pathnameProblem(raw) {
     );
 }
 
+/**
+ * Whether this build installs anything into a Foundry data directory.
+ *
+ * A `documentation` package compiles no packs and installs nowhere, so no note
+ * of its reaches a Foundry document and no pathname of its can be dead on a
+ * surface it never touches. A check that reports a missing Foundry address asks
+ * this first, so the one kind with no Foundry surface is not told about it.
+ *
+ * Read from {@link packageAddresses} rather than from a key, so "does this
+ * package have a Foundry root?" is answered in one place by the map that
+ * derives every other package's.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {boolean} Whether the package being built has a Foundry root.
+ */
+export function servesFoundry(config) {
+    const own = config?.contentPackage ? packageAddresses(config).get(config.contentPackage) : null;
+    return Boolean(own?.root);
+}
+
+/**
+ * Why a pathname has no Foundry address, or `""` when it has one.
+ *
+ * The sibling of {@link pathnameProblem} one step further on: that one asks
+ * whether a pathname is written correctly at all, and this one asks whether
+ * *this* build can turn a correctly written pathname into a path a Foundry
+ * install serves. Both answer in a sentence rather than a code, so the caller
+ * that holds a line and a column and the caller that holds only a file say the
+ * same thing about the same value.
+ *
+ * `""` for every pathname that resolves — and for the three shapes that
+ * legitimately reach Foundry untranslated: a URL, a protocol-relative
+ * `//host/…`, and a `/`-rooted path Foundry serves from its data root. A blank
+ * pathname is a deliberate blank and resolves to a blank on every surface, so
+ * it is not a problem either.
+ *
+ * `""` as well for a pathname {@link pathnameProblem} already refuses. That
+ * defect has its own finding naming its own replacement, and reporting a second
+ * one about the same characters would send the author to one mistake twice.
+ *
+ * @param {string|null|undefined} raw - The pathname, as authored.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string} The problem, as a finding's sentence, or `""`.
+ */
+export function foundryAddressProblem(raw, config) {
+    if (pathnameProblem(raw)) return "";
+    const forms = resolvePathname(raw, config);
+    if (forms === null || forms.foundry !== null) return "";
+    if (forms.package === PACKAGEBUILD_PACKAGE) {
+        return (
+            `\`${forms.authored}\` names a file the \`${PACKAGEBUILD_PACKAGE}\` package ` +
+            "ships, and Foundry installs no package of that name — package-build is an " +
+            "npm dependency of a package rather than a package of its own, so its files " +
+            "reach the website and the book and never a Foundry document. Address a " +
+            "`/`-rooted path or a URL"
+        );
+    }
+    if (forms.own) {
+        return (
+            `\`${forms.authored}\` names a file this package serves, and a ` +
+            "`documentation` package has no asset root to serve it from — Foundry " +
+            "installs no such package. Address a `/`-rooted path or a URL"
+        );
+    }
+    return (
+        `\`${forms.authored}\` names a file the \`${forms.package}\` package ships, and ` +
+        "this build declares no relationship with a package of that name, so there is " +
+        "no Foundry address to derive. Declare it under `relationships`, or address " +
+        "the file by a `/`-rooted path"
+    );
+}
+
 /**
  * Every game system this build compiles content for.
  *

package/engine/pdf-build.mjs

@@ -64,6 +64,20 @@
  * `.typ` source on disk, which is both the diagnostic and the thing a consumer
  * can compile by hand.
  *
+ * ## The faces are the toolchain's and the compiler's, never the machine's
+ *
+ * Every face the book sets resolves from one of two places that travel with the
+ * build: the faces this package ships — see {@link BOOK_FONTS_PATH} — and the
+ * ones the compiler embeds. The compile passes the shipped directory as
+ * `--font-path` and `--ignore-system-fonts` alongside it, so a machine carrying
+ * its own copy of a named family cannot quietly set a different book from the
+ * same source.
+ *
+ * `pdf.fonts.path` is searched as well, so a consumer naming a face of its own
+ * in `pdf.fonts` still resolves it — and a name nothing resolves is reported,
+ * because the compiler says so and a compile that says it still exits 0 with a
+ * book set in the fallback.
+ *
  * @module
  */
 
@@ -71,10 +85,12 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 import YAML from "yaml";
 
 import { loadPackConfig } from "./pack-config.mjs";
+import { routerFor } from "./pack-router.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { indexRecordsFor } from "./content-index.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
@@ -83,6 +99,8 @@ import { parseDocumentTree, runTreeFilters, planDocument } from "./pdf-toc.mjs";
 import { collectContentPages, siteGates, tableUniverse, gatesFailed } from "./site-build.mjs";
 import { resolveInfoboxRef, wikiContext } from "./site-index.mjs";
 import { resolveWebWikilinks } from "./web-wikilinks.mjs";
+import { linkFindingMessage } from "./wikilink-syntax.mjs";
+import { assetAddressIndex } from "./art-fields.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { imageSourcesIn } from "./content-images.mjs";
@@ -379,6 +397,13 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         skipDirectories: resolved.skipDirectories,
         records,
     });
+    // The address space an `![[…]]` embed resolves against — the same one the
+    // site builds, so one authored picture reaches both surfaces or neither.
+    const assets = assetAddressIndex(records, {
+        config: resolved,
+        foreign: gates.foreign,
+        types: gates.index?.contentTypes ?? [],
+    });
     const md = createParser(resolved.icons);
     const glyphs = resolveIconGlyphs(resolved.icons, resolved.pdf.iconFonts, findings);
 
@@ -478,6 +503,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             type: page.fm.type ?? null,
             errors: wikiErrors,
             foreignIndex: gates.foreign.index,
+            assets,
         });
         // Code fences are protected for the same reason every other pass
         // protects them: a wikilink shown as an example is prose about a
@@ -487,7 +513,10 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             findings.push({
                 file: page.file,
                 severity: "warning",
-                message: String(err.message ?? err),
+                // A link finding names a `reason` from the shared table and no
+                // sentence of its own; an embed's directive complaint carries
+                // the sentence instead.
+                message: err.message ?? (err.reason ? linkFindingMessage(err) : String(err)),
             });
         }
         stageImages(resolvedBody, page.file);
@@ -498,14 +527,13 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             images,
             headingOffset,
             anchorPrefix,
-            // An entry opens a page, so its first paragraph opens the page too.
-            dropCap: true,
         });
         // The infobox is generated content in document order — prepended,
         // before the prose. An image the note authored ahead of it still comes
         // first, because the image lives in the body and the body follows.
         const boxes = noteInfoboxes(page.fm, {
             resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
+            router: routerFor(resolved),
         });
         const panel = infoboxesToTypst(boxes, {
             link: (value) => linkToTypst(value, plan.links, labelFor),
@@ -615,6 +643,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     }
 
     const compiled = compileTypst(typPath, pdfPath, resolved.pdf);
+    findings.push(...compiled.findings);
     if (!compiled.ok) {
         findings.push({ file: typPath, severity: "error", message: compiled.message });
         return { built: false, reason: null, findings, typ: typPath, pdf: null, stats };
@@ -622,24 +651,113 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     return { built: true, reason: null, findings, typ: typPath, pdf: pdfPath, stats };
 }
 
+/**
+ * The faces the book is set in that the compiler does not carry itself.
+ *
+ * Resolved from this module rather than from the working directory, on the same
+ * rule the specification and `--version` follow: a consumer runs the build
+ * inside its own repository, and the faces it sets the book in are the ones
+ * that came with the toolchain version it resolved.
+ *
+ * What is here is the **sans**, in the three styles a heading can ask for, the
+ * superfamily's **mono** for a package that names it, and the licence they
+ * travel under. The serif is not: the compiler embeds one, and a second copy of
+ * a face it already carries is a file nothing selects.
+ *
+ * It is **not** an addressable asset root: the compiler matches a face by
+ * family name, so nothing addresses these files and nothing needs to.
+ *
+ * @type {string}
+ */
+export const BOOK_FONTS_PATH = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "assets",
+    "fonts",
+);
+
+/**
+ * The command line the compile runs, as data.
+ *
+ * Separate from running it so the flags that decide which faces are in play
+ * can be asserted without a compiler installed — which is the half of the
+ * invocation that changes what the book looks like.
+ *
+ * @param {string} typPath - The `.typ` file.
+ * @param {string} pdfPath - Where the PDF goes.
+ * @param {object} [pdf] - The resolved `pdf:` block.
+ * @returns {string[]} The arguments, in order.
+ */
+export function typstArgs(typPath, pdfPath, pdf = {}) {
+    // One flag, the paths joined by the platform's separator: the compiler
+    // takes a list, and the shipped faces come first so a consumer's own
+    // directory extends the set rather than standing in for it.
+    const fontPaths = [BOOK_FONTS_PATH];
+    if (pdf.fonts?.path) fontPaths.push(pdf.fonts.path);
+    return [
+        "compile",
+        "--ignore-system-fonts",
+        "--font-path",
+        fontPaths.join(path.delimiter),
+        typPath,
+        pdfPath,
+    ];
+}
+
+/**
+ * The compiler's own warnings, as findings.
+ *
+ * A compile that says `unknown font family` still exits 0 and still writes a
+ * book — one set in whatever face the fallback reached. That is the failure
+ * this surface is least able to see, so the compiler's warnings are read back
+ * and reported on the same terms as everything else the build finds.
+ *
+ * Typst writes a warning as a `warning:` line followed by a `┌─ file:line:col`
+ * locator over a source excerpt. The message and the position are taken; the
+ * excerpt is not, since the reader has the file.
+ *
+ * @param {string} output - What the compiler wrote to stderr.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: string, message: string}>} One finding per warning.
+ */
+export function typstWarnings(output) {
+    const lines = String(output || "").split("\n");
+    const findings = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const warned = /^warning: (.+)$/.exec(lines[i]);
+        if (!warned) continue;
+        const finding = { file: "", severity: "warning", message: warned[1].trim() };
+        const at = /^\s*┌─ (.+):(\d+):(\d+)\s*$/.exec(lines[i + 1] ?? "");
+        if (at) {
+            // The compiler writes the path relative to its own working
+            // directory, which is this process's, so resolving it there is what
+            // recovers the file a reader can open.
+            finding.file = path.resolve(at[1]);
+            finding.line = Number(at[2]);
+            finding.column = Number(at[3]);
+        }
+        findings.push(finding);
+    }
+    return findings;
+}
+
 /**
  * Run Typst over the emitted source.
  *
  * @param {string} typPath - The `.typ` file.
  * @param {string} pdfPath - Where the PDF goes.
  * @param {object} pdf - The resolved `pdf:` block.
- * @returns {{ok: boolean, message: string}} What happened.
+ * @returns {{ok: boolean, message: string, findings: object[]}} What happened,
+ *   and what the compiler warned about on the way.
  */
 export function compileTypst(typPath, pdfPath, pdf = {}) {
     const binary = pdf.binary || "typst";
-    const args = ["compile"];
-    if (pdf.fonts?.path) args.push("--font-path", pdf.fonts.path);
-    args.push(typPath, pdfPath);
+    const args = typstArgs(typPath, pdfPath, pdf);
     let result;
     try {
         result = spawnSync(binary, args, { encoding: "utf8" });
     } catch (err) {
-        return { ok: false, message: `could not run \`${binary}\`: ${err.message}` };
+        return { ok: false, message: `could not run \`${binary}\`: ${err.message}`, findings: [] };
     }
     if (result.error) {
         const missing = /** @type {any} */ (result.error).code === "ENOENT";
@@ -651,13 +769,18 @@ export function compileTypst(typPath, pdfPath, pdf = {}) {
                     "`typst compile` over it produces the book. Name another binary with " +
                     "`pdf.binary`."
                 :   `could not run \`${binary}\`: ${result.error.message}`,
+            findings: [],
         };
     }
     if (result.status !== 0) {
         const detail = String(result.stderr || result.stdout || "")
             .trim()
             .split("\n")[0];
-        return { ok: false, message: `\`${binary} compile\` failed: ${detail}` };
+        return {
+            ok: false,
+            message: `\`${binary} compile\` failed: ${detail}`,
+            findings: [],
+        };
     }
-    return { ok: true, message: "" };
+    return { ok: true, message: "", findings: typstWarnings(result.stderr) };
 }

package/engine/pdf-render.mjs

@@ -168,7 +168,6 @@ export function createParser(registry) {
  *   note's own `##` nests beneath the entry heading the book gave it.
  * @param {string} [opts.anchorPrefix] - The entry's anchor, which namespaces
  *   every `{#slug}` the body declares.
- * @param {boolean} [opts.dropCap] - Whether to open the body with a raised
  *   capital. Set for an entry, which begins a page; not for front matter or a
  *   prose file, which carry headings of their own.
  * @returns {string} Typst markup.
@@ -181,7 +180,6 @@ export function markdownToTypst(markdown, opts = {}) {
         images = new Map(),
         headingOffset = 0,
         anchorPrefix = "",
-        dropCap = false,
     } = opts;
     const tokens = md.parse(String(markdown ?? ""), {});
     // One map for the whole body, not one per block: a heading inside a
@@ -194,7 +192,6 @@ export function markdownToTypst(markdown, opts = {}) {
         images,
         headingOffset,
         anchorPrefix,
-        dropCap,
         seen: new Map(),
     });
 }
@@ -258,7 +255,7 @@ function renderBlock(tokens, i, out, ctx) {
             return 3;
         }
         case "paragraph_open": {
-            out.push(`\n${openingParagraph(renderInline(tokens[i + 1], ctx), ctx)}\n\n`);
+            out.push(`\n${renderInline(tokens[i + 1], ctx)}\n\n`);
             return 3;
         }
         case "fence":
@@ -271,7 +268,7 @@ function renderBlock(tokens, i, out, ctx) {
             return 1;
         case "blockquote_open": {
             const end = matching(tokens, i, "blockquote_open", "blockquote_close");
-            const inner = renderTokens(tokens.slice(i + 1, end), { ...ctx, dropCap: false });
+            const inner = renderTokens(tokens.slice(i + 1, end), { ...ctx });
             out.push(`\n#quote(block: true)[${inner}]\n\n`);
             return end - i + 1;
         }
@@ -298,29 +295,6 @@ function renderBlock(tokens, i, out, ctx) {
     }
 }
 
-/**
- * The first paragraph of an entry, opened with a raised capital.
- *
- * Only the first, and only when it begins with a letter: a paragraph opening
- * on a link, a bold run or a number has no character to raise, and raising
- * whatever happened to be first would put a 26pt accent on a bracket. The
- * chance is spent either way — a body opens once — so a paragraph that cannot
- * take the capital simply sets as itself.
- *
- * @param {string} rendered - The paragraph's Typst markup.
- * @param {object} ctx - Render context.
- * @returns {string} The same markup, or it with a raised capital.
- */
-function openingParagraph(rendered, ctx) {
-    if (!ctx.dropCap) return rendered;
-    ctx.dropCap = false;
-    // A letter is never escaped, so the first character of the markup is the
-    // first character of the prose whenever the prose starts with one.
-    const match = /^(\p{L})([\s\S]*)$/u.exec(rendered);
-    if (!match) return rendered;
-    return `#book-dropcap[${match[1]}]#h(1pt)${match[2]}`;
-}
-
 /**
  * A heading's text, and the `{#slug}` it may end with.
  *
@@ -438,7 +412,7 @@ function listItems(tokens, start, end, ctx) {
             continue;
         }
         const close = matching(tokens, i, "list_item_open", "list_item_close");
-        items.push(renderTokens(tokens.slice(i + 1, close), { ...ctx, dropCap: false }));
+        items.push(renderTokens(tokens.slice(i + 1, close), { ...ctx }));
         i = close + 1;
     }
     return items;
@@ -825,6 +799,7 @@ export function bookTypstPreamble() {
         '#let book-ink = rgb("#241f1a")',
         '#let book-paper = rgb("#f4efe4")',
         '#let book-accent = rgb("#7c3b1e")',
+        '#let book-head = rgb("#5e2b14")',
         '#let book-faint = rgb("#6b6357")',
         "#let book-ornament = box(baseline: 1pt, " +
             "rotate(45deg, rect(width: 3pt, height: 3pt, fill: book-accent)))",
@@ -835,16 +810,34 @@ export function bookTypstPreamble() {
             "}",
         // A heading justifies and hyphenates like body text unless told
         // otherwise, and both make a display line look broken.
-        "#let book-sechead(it) = block(width: 100%, above: 0.9em, below: 0.5em, " +
-            "breakable: false)[\n" +
-            "  #set par(justify: false, first-line-indent: 0em)\n" +
-            "  #set text(hyphenate: false)\n" +
-            '  #text(size: 11pt, weight: "bold", tracking: 1.6pt, fill: book-accent)[#upper(it.body)]\n' +
-            "  #v(-0.35em)\n" +
-            "  #line(length: 100%, stroke: 0.5pt + book-accent)\n" +
-            "]",
-        '#let book-dropcap(letter) = text(size: 26pt, weight: "bold", fill: book-accent, ' +
-            "baseline: 5pt)[#letter]",
+        //
+        // Size, weight and the space above follow the level, so a parent reads
+        // as one without the words being read. The rule belongs to the note's own
+        // top level alone; every level under it is set apart by space. Headings set
+        // in the sans face and in the case they were authored in, so neither
+        // capitals nor tracking is carrying the distinction. The scale starts
+        // at 3: `book-plate` shadows this rule while it draws the title, so
+        // the section landing and the entry title never arrive here, and the
+        // headings that do are the note's own.
+        "#let book-sechead(it) = {\n" +
+            "  let lv = it.level\n" +
+            "  let size = if lv <= 3 { 26pt } else if lv == 4 { 19pt }\n" +
+            "    else if lv == 5 { 14pt } else { 11pt }\n" +
+            "  let above = if lv <= 3 { 2.5em } else if lv == 4 { 2.0em }\n" +
+            "    else { 1.0em }\n" +
+            "  let below = if lv <= 3 { 0.5em } else if lv == 4 { 0.36em }\n" +
+            "    else { 0.28em }\n" +
+            '  let weight = if lv <= 5 { "bold" } else { "regular" }\n' +
+            "  block(width: 100%, above: above, below: below, breakable: false)[\n" +
+            "    #set par(justify: false, first-line-indent: 0em)\n" +
+            "    #set text(hyphenate: false)\n" +
+            "    #text(size: size, weight: weight, fill: book-head)[#it.body]\n" +
+            "    #if lv <= 3 {\n" +
+            "      v(-0.30em)\n" +
+            "      line(length: 100%, stroke: 0.5pt + book-accent)\n" +
+            "    }\n" +
+            "  ]\n" +
+            "}",
         // The plate bleeds off the paper: the placed panel is the full width of
         // the sheet and starts a margin above and to the left of wherever the
         // flow has reached, which on an entry's first page is the top corner.
@@ -1014,7 +1007,9 @@ export function bookTypstPreamble() {
  * @param {string} opts.title - The document's title.
  * @param {string} [opts.subtitle] - Shown under it on the title page.
  * @param {string[]} [opts.front] - Rendered Typst for each front-matter file.
- * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names.
+ * @param {object} [opts.fonts] - `{ serif, sans, mono }` family names. Each
+ *   falls back to the face the toolchain ships or the compiler embeds, so a
+ *   caller that names none still sets the book in all three.
  * @param {string} [opts.version] - Stamped on the title page when given.
  * @param {string} [opts.preamble] - Definitions the bodies call, emitted once
  *   above the title page. A panel every entry draws is a set of rules stated
@@ -1036,8 +1031,13 @@ export function renderBook({
     preamble = "",
     banners = new Map(),
 } = {}) {
+    // The two halves of one superfamily, chosen together: matched metrics are
+    // most of why the sans can carry every heading over a serif body without
+    // the page reading as two books. The mono is a separate claim — the
+    // superfamily's own is missing the Latin Extended Additional letters this
+    // corpus spells names with, where the compiler's embedded face carries them.
     const serif = fonts.serif || "Libertinus Serif";
-    const sans = fonts.sans || serif;
+    const sans = fonts.sans || "Libertinus Sans";
     const mono = fonts.mono || "DejaVu Sans Mono";
     const out = [];
 

package/engine/scenes.mjs

@@ -53,7 +53,6 @@ import log from "loglevel";
 import {
     parseMarkdownFile,
     sohlField,
-    resolveImg,
     resolveName,
     slugify,
     defaultStats,
@@ -130,15 +129,15 @@ export class Scenes extends BasePackCompiler {
     static label = "map";
 
     /**
-     * A map note's `img` is its background art, and it is **required**: the map
-     * compiler refuses a note without one. It lands on the scene's level rather
-     * than on a property spelled `img`, which makes no difference to the
-     * question this declaration answers — the authored path reaches the output.
-     * The place Adventure this pass bundles carries it too.
+     * A map note's `bgImage` is its background art, and it is **required**: the
+     * map compiler refuses a note without one. It lands on the scene's level
+     * rather than on a property spelled `img`, which makes no difference to the
+     * question this declaration answers — the authored address reaches the
+     * output. The place Adventure this pass bundles carries it too.
      *
      * @type {readonly string[]}
      */
-    static emitsArt = Object.freeze(["img"]);
+    static emitsArt = Object.freeze(["bgImage"]);
 
     /** @type {string} */
     adventureDir;
@@ -152,13 +151,14 @@ export class Scenes extends BasePackCompiler {
 
     constructor({
         contentBase,
+        assetsBase,
         dest,
         skipDirectories,
         companionDests = {},
         folderResolver = () => null,
         repoRoot = process.cwd(),
     }) {
-        super({ contentBase, dest, folderResolver, skipDirectories });
+        super({ contentBase, assetsBase, dest, folderResolver, skipDirectories });
         if (!companionDests.adventures) {
             throw new Error("Scenes compiler requires an `adventures` companion destination");
         }
@@ -426,6 +426,9 @@ export class Scenes extends BasePackCompiler {
         const warnings = [];
         const scene = buildScene(fm, {
             packageId: foundryPackageId(),
+            // The art resolver, so the map pass turns an address into the path
+            // each surface serves without holding an index of its own.
+            art: (value, key, type) => this.artPathOf(value, key, type),
             name,
             folder,
             stats: this.stats,
@@ -473,7 +476,7 @@ export class Scenes extends BasePackCompiler {
             this.places.set(placeKey, {
                 key: placeKey,
                 name: sohlField(fm, "placeName", null) || name,
-                img: resolveImg(sohlField(fm, "img", null)),
+                img: this.artPath(fm, "bgImage"),
                 pinned: false,
                 scenes: [],
                 journal: [],