@heroiclands/package-build 22.15.0 → 22.16.0

package/engine/pdf-build.mjs

@@ -32,24 +32,15 @@
  * the site publishes every page, and the book publishes what its document tree
  * asked for.
  *
- * ## `publish.site` is the switch, and it is the only switch
- *
- * `homepage` mode fences the content surfaces off: the tree is not walked for
- * pages, whatever else the configuration declares. A
- * PDF of the content tree is a content surface by any reading — arguably the
- * most portable one there is — so it is fenced on exactly the same terms, by
- * asking the same {@link module:content-config.publishesContentPages} the
- * site build asks. Four of the six packages that would adopt this run
- * `homepage`, and a PDF that appeared there would breach the fence silently:
- * nothing in those packages' configuration would say so. So the fence is
- * checked **before** the tree is read, and the command says why it built
- * nothing rather than emitting an empty document.
+ * The book builds when the authored tree contains content pages. The same
+ * {@link module:content-config.publishesContentPages} decision governs the
+ * site and the content index.
  *
  * ## Every gate reports; none exits
  *
  * A filter that selects nothing, a `file:` that resolves nowhere, a table that
  * will not run and a missing Typst binary are all findings handed back to the
- * caller. `bin/content-build.mjs` decides what to do about them — which is the
+ * caller. `bin/package-build.mjs` decides what to do about them — which is the
  * rule the whole engine is built on, and what lets one pass serve a lint, a
  * build step and a unit test.
  *
@@ -96,15 +87,32 @@ import { indexRecordsFor } from "./content-index.mjs";
 import { isNoteRecord, isStub, noteFile } from "./index-records.mjs";
 import { openNotesDatabase, prepareTreeSqlTables } from "./sql-tables.mjs";
 import { parseDocumentTree, runTreeFilters, planDocument } from "./pdf-toc.mjs";
-import { collectContentPages, siteGates, tableUniverse, gatesFailed } from "./site-build.mjs";
+import {
+    collectContentPages,
+    siteGates,
+    tableUniverse,
+    gatesFailed,
+    resolveSitePass,
+} from "./site-build.mjs";
 import { resolveInfoboxRef, wikiContext } from "./site-index.mjs";
 import { resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { linkFindingMessage } from "./wikilink-syntax.mjs";
 import { artPathname, assetAddressIndex } from "./art-fields.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { renderSecretBlocks } from "./content-secrets.mjs";
+import { scanAdmonitions } from "./content-admonitions.mjs";
+import { numberCaptions, scanCaptions } from "./content-captions.mjs";
 import { protectCode } from "./code-fences.mjs";
-import { imageSourcesIn } from "./content-images.mjs";
+import { imagesIn, parseImageDirective } from "./content-images.mjs";
+import {
+    PDF_IMAGE_INCHES,
+    PDF_PAGE,
+    pdfColumnWidth,
+    pdfTextHeight,
+    pdfTextWidth,
+    resamplePdfImages,
+} from "./pdf-images.mjs";
 import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
 import {
     createParser,
@@ -114,7 +122,7 @@ import {
     resolveDanglingLabels,
 } from "./pdf-render.mjs";
 import { draftNoticeTypst } from "./draft-notice.mjs";
-import { isDraftNote } from "./note-vocabulary.mjs";
+import { isDraftNote, isGmNote } from "./note-vocabulary.mjs";
 import { infoboxTypstPreamble, infoboxesToTypst, linkToTypst } from "./infobox-render.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
 import { resolveIconGlyphs } from "./pdf-fonts.mjs";
@@ -304,8 +312,9 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         return {
             built: false,
             reason:
-                "`publish.site` is `homepage`, which fences the content surfaces off — " +
-                "the tree is not walked and no book is built. Publish content to build one.",
+                fs.existsSync(resolved.paths.content) ?
+                    "The content tree contains only a homepage, so there is no book to build."
+                :   "this package has no content tree, so there is nothing to print",
             findings,
             typ: null,
             pdf: null,
@@ -354,11 +363,11 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     });
 
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "content-pdf-"));
-    const db = await openNotesDatabase(records, { dir });
+    const db = await openNotesDatabase(records, { dir, audience: "public" });
     const ran = await runTreeFilters(parsed.nodes, db, {
         // A stub is a note and is deliberately in the corpus, but it has no
         // body — selecting one would print a blank page under its name.
-        keep: (record) => isNoteRecord(record) && !isStub(record),
+        keep: (record) => isNoteRecord(record) && !isStub(record) && !isGmNote(record),
         text: tree.text,
     });
     findings.push(...ran.findings.map((f) => ({ file: resolved.pdf.document, ...f })));
@@ -403,6 +412,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         config: resolved,
         skipDirectories: resolved.skipDirectories,
         records,
+        audience: "public",
     });
     // The address space an `![[…]]` embed resolves against — the same one the
     // site builds, so one authored picture reaches both surfaces or neither.
@@ -422,6 +432,8 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
 
     /** @type {Map<string, string>} Authored address → the staged file's path. */
     const images = new Map();
+    /** @type {Map<string, {from: string, to: string, relative: string, file: string, uses: Array<{width: number, height: number}>}>} */
+    const imageCandidates = new Map();
     /** @type {Set<string>} Addresses already looked for, staged or not. */
     const seenImages = new Set();
 
@@ -434,11 +446,25 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
      *
      * @param {string} body - The rendered markdown.
      * @param {string} file - The note, for the finding.
+     * @param {number} columns - The page's column count.
      * @returns {void}
      */
-    const stageImages = (body, file) => {
-        for (const src of imageSourcesIn(body)) {
-            if (seenImages.has(src)) continue;
+    const stageImages = (body, file, columns = 2) => {
+        for (const image of imagesIn(body)) {
+            const src = image.src;
+            const directive = parseImageDirective(image.directive);
+            const wide =
+                directive.size === "full-width" || directive.classes.includes("full-width");
+            const availableWidth = wide ? pdfTextWidth : pdfColumnWidth(columns);
+            const use = {
+                width: Math.min(PDF_IMAGE_INCHES[directive.size] ?? availableWidth, availableWidth),
+                height: pdfTextHeight * 0.8,
+            };
+            if (seenImages.has(src)) {
+                const stagedTo = images.get(src);
+                if (stagedTo) imageCandidates.get(stagedTo)?.uses.push(use);
+                continue;
+            }
             seenImages.add(src);
             // An **error**, where a picture the book cannot carry is a warning:
             // this pathname resolves on no surface at all, and the replacement
@@ -476,6 +502,15 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                 continue;
             }
             images.set(src, staged.to);
+            const candidate = imageCandidates.get(staged.to);
+            if (candidate) candidate.uses.push(use);
+            else
+                imageCandidates.set(staged.to, {
+                    ...staged,
+                    relative: path.relative(resolved.rootDir, staged.from),
+                    file,
+                    uses: [use],
+                });
         }
     };
 
@@ -485,12 +520,37 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
      * @param {object} page - A collected page.
      * @param {number} headingOffset - Where the book put this entry.
      * @param {string} anchorPrefix - The entry's anchor, namespacing its sections.
+     * @param {number} columns - The entry's page columns.
      * @returns {string} Typst markup.
      */
-    const renderPage = (page, headingOffset, anchorPrefix) => {
+    const captionCounts = { code: 0, table: 0, figure: 0, prose: 0 };
+    const frontCaptions = new Map();
+    for (const file of resolved.pdf.front) {
+        try {
+            const scan = scanCaptions(fs.readFileSync(file, "utf8"));
+            frontCaptions.set(file, numberCaptions(scan.captions, captionCounts));
+            for (const error of scan.errors)
+                findings.push({
+                    file,
+                    line: error.line,
+                    column: error.column,
+                    severity: "error",
+                    message: error.message,
+                });
+        } catch {
+            // The rendering pass reports an unreadable front-matter file.
+        }
+    }
+    const pass = resolveSitePass(resolved.site?.pass, {
+        ...resolved.site?.passOptions,
+        repoRoot: resolved.rootDir,
+        config: resolved,
+        book: true,
+    });
+    const renderPage = (page, headingOffset, anchorPrefix, columns) => {
         const src = page.relPath ?? page.base;
         const wikiErrors = [];
-        const { markdown, errors } = expandContentTables(page.body, {
+        const { markdown, errors, lineMap } = expandContentTables(page.body, {
             docs: universe.get(page.pkg) ?? [],
             linkable: (d) => Boolean(d.fm.shortcode),
             source: src,
@@ -512,10 +572,34 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             foreignIndex: gates.foreign.index,
             assets,
         });
+        const captionScan = scanCaptions(markdown);
+        const numberedCaptions = numberCaptions(captionScan.captions, captionCounts);
+        linkCtx.captionLabels = new Map(
+            numberedCaptions.map((caption) => [caption.id, caption.label]),
+        );
+        for (const error of captionScan.errors)
+            findings.push({
+                file: page.file,
+                line: (page.bodyLine ?? 1) + (lineMap[error.line - 1]?.line ?? error.line - 1),
+                column: error.column,
+                severity: "error",
+                message: error.message,
+            });
+        linkCtx.output = "book";
         // Code fences are protected for the same reason every other pass
         // protects them: a wikilink shown as an example is prose about a
         // wikilink, and resolving it would make the example impossible to write.
-        const resolvedBody = protectCode(markdown, (text) => resolveWebWikilinks(text, linkCtx));
+        const expressions = renderMarkdownExpressions(markdown, {
+            fm: page.fm,
+            dates: gates.index.dateContext,
+            sqlResults: sqlTables?.inline?.get(page.file),
+            file: page.file,
+            bodyLine: page.bodyLine,
+        });
+        findings.push(...expressions.findings);
+        const resolvedBody = protectCode(expressions.markdown, (text) =>
+            resolveWebWikilinks(pass.beforeLinks ? pass.beforeLinks(text, page) : text, linkCtx),
+        );
         for (const err of wikiErrors) {
             findings.push({
                 file: page.file,
@@ -536,7 +620,16 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                 message: error.message,
             });
         }
-        stageImages(secrets.markdown, page.file);
+        for (const error of scanAdmonitions(page.body).errors) {
+            findings.push({
+                file: page.file,
+                line: (page.bodyLine ?? 1) + error.line - 1,
+                column: error.column,
+                severity: "error",
+                message: error.message,
+            });
+        }
+        stageImages(secrets.markdown, page.file, columns);
         const prose = markdownToTypst(secrets.markdown, {
             md,
             links: plan.links,
@@ -544,6 +637,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             images,
             headingOffset,
             anchorPrefix,
+            captions: numberedCaptions,
         });
         // The infobox is generated content in document order — prepended,
         // before the prose. An image the note authored ahead of it still comes
@@ -551,6 +645,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         const boxes = noteInfoboxes(page.fm, {
             resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
             router: routerFor(resolved),
+            dates: gates.index.dateContext,
         });
         const panel = infoboxesToTypst(boxes, {
             link: (value) => linkToTypst(value, plan.links, labelFor),
@@ -577,7 +672,10 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             // entry. A note's body starts at `##` — its name is frontmatter, not
             // an H1 — so an offset of the entry's depth puts that `##` one level
             // below the entry heading at `depth + 1`, which is where it belongs.
-            bodies.set(entry.anchor, renderPage(page, entry.depth, entry.anchor));
+            bodies.set(
+                entry.anchor,
+                renderPage(page, entry.depth, entry.anchor, entry.presentation?.page?.columns ?? 2),
+            );
             continue;
         }
         if (entry.kind === "prose") {
@@ -593,7 +691,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                 });
                 continue;
             }
-            stageImages(text, file);
+            stageImages(text, file, entry.presentation?.page?.columns ?? 2);
             bodies.set(
                 entry.anchor,
                 markdownToTypst(text, {
@@ -603,6 +701,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                     images,
                     headingOffset: entry.depth,
                     anchorPrefix: entry.anchor,
+                    captions: numberCaptions(scanCaptions(text).captions, captionCounts),
                 }),
             );
         }
@@ -617,15 +716,17 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         });
     }
 
-    const front = resolved.pdf.front.map((file) => {
+    const front = resolved.pdf.front.map((file, index) => {
         try {
             const text = fs.readFileSync(file, "utf8");
-            stageImages(text, file);
+            stageImages(text, file, 1);
             return markdownToTypst(text, {
                 md,
                 links: plan.links,
                 glyphs,
                 images,
+                footnotePrefix: `footnote-front-${index + 1}`,
+                captions: frontCaptions.get(file),
             });
         } catch {
             findings.push({
@@ -638,9 +739,53 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     });
 
     const banners = stageBanners(plan.entries, resolved, outDir, findings);
+    for (const [declared, to] of banners) {
+        const from = path.resolve(resolved.rootDir, declared);
+        imageCandidates.set(`banner:${declared}`, {
+            from,
+            to,
+            relative: path.relative(resolved.rootDir, from),
+            file: resolved.pdf.document,
+            uses: [{ width: PDF_PAGE.width, height: Infinity }],
+        });
+    }
 
-    /** @type {Map<string, {path: string, title: string}>} Entry anchor → map page. */
+    /** @type {Map<string, Array<{path: string, title: string}>>} Entry anchor → map pages. */
     const maps = new Map();
+    const addMapPage = (anchor, page) => {
+        if (!maps.has(anchor)) maps.set(anchor, []);
+        maps.get(anchor).push(page);
+    };
+    const stageMapBackground = (entry, value, title) => {
+        const file = noteFile(contentBase, entry.record);
+        const found = artPathname(assets, value, "image", ["image", "icon"]);
+        const staged = stagedImagePath(found.pathname ?? value, resolved);
+        if (!staged || !fs.existsSync(staged.from)) {
+            findings.push({
+                file,
+                severity: "warning",
+                message: `the map background "${value}" cannot be resolved for the book`,
+            });
+            return;
+        }
+        const target = path.join(outDir, staged.to);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.copyFileSync(staged.from, target);
+        addMapPage(entry.anchor, { path: staged.to, title });
+        const candidate = imageCandidates.get(staged.to);
+        const use = {
+            width: PDF_PAGE.height - 2 * PDF_PAGE.margin,
+            height: pdfTextWidth - 2 / 2.54,
+        };
+        if (candidate) candidate.uses.push(use);
+        else
+            imageCandidates.set(staged.to, {
+                ...staged,
+                relative: path.relative(resolved.rootDir, staged.from),
+                file,
+                uses: [use],
+            });
+    };
     const world = mapWorld({
         records,
         foreignIndex: gates.foreign.index,
@@ -661,7 +806,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         const drawn = buildMaps({ world, outDir: mapDir, from: centres });
         findings.push(...drawn.findings);
         for (const entry of mappedEntries) {
-            maps.set(entry.anchor, {
+            addMapPage(entry.anchor, {
                 path: `maps/from-${entry.record.shortcode}.svg`,
                 title: `From here: ${entry.record.name?.full ?? entry.record.shortcode}`,
             });
@@ -669,27 +814,26 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     }
     for (const entry of plan.entries) {
         if (entry.kind !== "note" || entry.record?.type !== "map") continue;
-        if (entry.record.subType !== "regionalmap") continue;
-        const image = entry.record.data?.bgImage;
-        if (!image) continue;
-        const found = artPathname(assets, image, "image", ["image", "icon"]);
-        if (!found.pathname) {
-            findings.push({
-                file: noteFile(contentBase, entry.record),
-                severity: "warning",
-                message: `the regional map's background "${image}" cannot be resolved for the book`,
-            });
+        const title = entry.record.name?.full ?? entry.record.shortcode;
+        if (["regionalmap", "totm"].includes(entry.record.subType)) {
+            if (entry.record.data?.bgImage) {
+                stageMapBackground(entry, entry.record.data.bgImage, title);
+            }
             continue;
         }
-        const staged = stagedImagePath(found.pathname, resolved);
-        if (!staged || !staged.from.toLowerCase().endsWith(".svg")) continue;
-        const target = path.join(outDir, staged.to);
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        fs.copyFileSync(staged.from, target);
-        maps.set(entry.anchor, {
-            path: staged.to,
-            title: entry.record.name?.full ?? entry.record.shortcode,
-        });
+        if (!["battlemap", "localmap"].includes(entry.record.subType)) continue;
+        for (const [index, level] of (entry.record.data?.scene?.levels ?? []).entries()) {
+            const paths = [
+                `.levels[${index}].background.src`,
+                ...(level._id ? [`.levels[${level._id}].background.src`] : []),
+            ];
+            const fixup = (entry.record.data?.fixup ?? []).find((item) =>
+                paths.includes(item.path),
+            );
+            const value = fixup?.value ?? level.background?.src;
+            if (value)
+                stageMapBackground(entry, value, level.name ? `${title}: ${level.name}` : title);
+        }
     }
 
     const assembled = renderBook({
@@ -713,18 +857,36 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
     const pdfPath = path.join(outDir, stem);
     fs.writeFileSync(typPath, source);
 
+    const imageReports = await resamplePdfImages(imageCandidates, outDir);
+
     const stats = { ...plan.stats, entries: plan.entries.length, bytes: source.length };
     if (!compile) {
-        return { built: true, reason: null, findings, typ: typPath, pdf: null, stats };
+        return {
+            built: true,
+            reason: null,
+            findings,
+            imageReports,
+            typ: typPath,
+            pdf: null,
+            stats,
+        };
     }
 
     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 };
+        return {
+            built: false,
+            reason: null,
+            findings,
+            imageReports,
+            typ: typPath,
+            pdf: null,
+            stats,
+        };
     }
-    return { built: true, reason: null, findings, typ: typPath, pdf: pdfPath, stats };
+    return { built: true, reason: null, findings, imageReports, typ: typPath, pdf: pdfPath, stats };
 }
 
 /**

package/engine/pdf-fonts.mjs

@@ -37,7 +37,7 @@
  * ## Nothing here fails a build
  *
  * A font that cannot be read, or a name it does not carry, is a **finding** and
- * the icon falls back to its literal `:icon-…:` text. That is the failure mode
+ * the icon falls back to its literal `:icon …:` text. That is the failure mode
  * {@link module:engine/content-icons} was designed around — visible on the
  * page, where an author is looking — and it is strictly better than a tofu box
  * or a silently missing glyph.
@@ -399,7 +399,7 @@ export function resolveIconGlyphs(registry, iconFonts = {}, findings = []) {
                 file: font.file,
                 severity: "warning",
                 message:
-                    `\`:icon-${name}:\` asks for glyph \`${glyphName}\`, which ` +
+                    `\`:icon ${name}:\` asks for glyph \`${glyphName}\`, which ` +
                     `${path0(font.file)} does not carry — it prints as its name`,
             });
             continue;

package/engine/pdf-images.mjs

@@ -0,0 +1,82 @@
+/*
+ * 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
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import sharp from "sharp";
+
+/** Print geometry in inches; Typst's default column gutter is 4% of the text width. */
+export const PDF_PAGE = Object.freeze({
+    width: 8.5,
+    height: 11,
+    margin: 1.9 / 2.54,
+    dpi: 300,
+    quality: 82,
+});
+
+/** Named image widths in inches, matching the book renderer's Typst sizes. */
+export const PDF_IMAGE_INCHES = Object.freeze({
+    small: 1.6 / 2.54,
+    medium: 3.2 / 2.54,
+    large: 5.6 / 2.54,
+    xlarge: 8 / 2.54,
+});
+
+/** Usable width of a portrait page in inches. */
+export const pdfTextWidth = PDF_PAGE.width - 2 * PDF_PAGE.margin;
+/** Usable height of a portrait page in inches. */
+export const pdfTextHeight = PDF_PAGE.height - 2 * PDF_PAGE.margin;
+/** Width of a portrait page's text column in inches. */
+export const pdfColumnWidth = (columns = 2) =>
+    (pdfTextWidth * (1 - 0.04 * (columns - 1))) / columns;
+
+/**
+ * Optimize staged raster images without changing their authored files.
+ *
+ * @param {Map<string, {from: string, to: string, relative: string, file: string,
+ *   uses: Array<{width: number, height: number}>}>} candidates
+ * @param {string} outDir - PDF staging directory.
+ * @returns {Promise<object[]>} Image reports with the authored file location.
+ */
+export async function resamplePdfImages(candidates, outDir) {
+    const reports = [];
+    for (const candidate of candidates.values()) {
+        const extension = path.extname(candidate.to).toLowerCase();
+        if (![".jpg", ".jpeg", ".png", ".webp", ".avif"].includes(extension)) continue;
+        const relative = candidate.relative.replaceAll(path.sep, "/");
+        const destination = path.join(outDir, candidate.to);
+        const original = await fs.readFile(destination);
+        const metadata = await sharp(original).metadata();
+        if (!metadata.width || !metadata.height) continue;
+        const ratio = metadata.width / metadata.height;
+        const target = Math.round(
+            Math.max(
+                ...candidate.uses.map(({ width, height }) => Math.min(width, height * ratio)),
+            ) * PDF_PAGE.dpi,
+        );
+        if (metadata.width <= target) continue;
+        let pipeline = sharp(original).resize({ width: target, withoutEnlargement: true });
+        if (extension === ".jpg" || extension === ".jpeg")
+            pipeline = pipeline.jpeg({ quality: PDF_PAGE.quality });
+        if (extension === ".webp") pipeline = pipeline.webp({ quality: PDF_PAGE.quality });
+        if (extension === ".avif") pipeline = pipeline.avif({ quality: PDF_PAGE.quality });
+        if (extension === ".png") pipeline = pipeline.png();
+        const output = await pipeline.toBuffer();
+        await fs.writeFile(destination, output);
+        reports.push({
+            file: candidate.file,
+            message: `book image ${relative}: ${metadata.width}×${metadata.height} → ${target} px wide; ${original.length} → ${output.length} bytes`,
+        });
+    }
+    return reports;
+}