@heroiclands/package-build 25.5.4 → 25.5.5

package/engine/pdf-render.mjs

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

package/engine/preview-index.mjs

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

package/engine/site-build.mjs

@@ -51,6 +51,7 @@
  * @module
  */
 
+import { scanPageBreaks } from "./page-breaks.mjs";
 import { scanAlerts } from "./content-alerts.mjs";
 import { positionOfYamlPath } from "./diagnostics.mjs";
 import { decodeNoteAddresses, noteAddressContext } from "./note-addresses.mjs";
@@ -695,7 +696,9 @@ export function renderSitePage(
         figuresByAddress = new Map(),
         events,
         drawings = new Map(),
-        runs = runContext(config),
+        runs = runContext(config, undefined, {
+            referenceName: (target) => resolveInfoboxRef(index, target)?.name,
+        }),
     },
 ) {
     const secretErrors = [];
@@ -797,6 +800,7 @@ export function renderSitePage(
     for (const error of [
         ...scanBlocks(page.body).errors,
         ...scanAlerts(page.body).errors,
+        ...scanPageBreaks(page.body).errors,
         ...scanSpans(page.body).errors,
         ...scanRuns(page.body, runs).errors,
         ...markupAnchorFindings(page.body),
@@ -985,7 +989,9 @@ export function renderPages(pages, options) {
     // What each page renders as, held until the graph is whole.
     /** @type {Array<{page: object, markdown: string, figures: object[], data: object}>} */
     const rendered = [];
-    const runs = runContext(config, records);
+    const runs = runContext(config, records, {
+        referenceName: (target) => resolveInfoboxRef(index, target)?.name,
+    });
 
     const renderOne = (page) =>
         renderSitePage(page, {
@@ -1141,6 +1147,7 @@ export function sitePageDecorator(config, index) {
  * @param {object} [options] - Options.
  * @param {object} [options.config] - A resolved configuration; loaded when
  *   omitted.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @param {Map<string, object[]>} [options.sqlTables] - Prepared `sql` results,
  *   keyed by the note's absolute file, from
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
@@ -1157,7 +1164,7 @@ export function sitePageDecorator(config, index) {
  *   against the rest of the build, or returns `null` when its address, name
  *   or type changed and the whole site must be built again.
  */
-export function buildSite({ config, sqlTables } = {}) {
+export function buildSite({ config, sqlTables, progress = () => {} } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
@@ -1247,6 +1254,7 @@ export function buildSite({ config, sqlTables } = {}) {
     // the content tree for pages, so `sohl-kethira-basic` and `harn-adventures`
     // cannot publish one whatever else their `site:` block declares.
     if (!publishesContent) {
+        progress(`rendering ${homepages.length} page(s)`);
         return {
             gates: emptyGates(),
             manifests: null,
@@ -1322,6 +1330,7 @@ export function buildSite({ config, sqlTables } = {}) {
         };
     }
 
+    progress(`rendering ${pages.length + homepages.length} page(s)`);
     const pass = resolveSitePass(site.pass, {
         ...site.passOptions,
         repoRoot: resolved.rootDir,

package/engine/site-preview.mjs

@@ -13,6 +13,7 @@
 
 /** Buffer-only HTML preview shared by editors and external renderers. @module */
 
+import { scanPageBreaks } from "./page-breaks.mjs";
 import { sharedContentRules } from "./content-styles.mjs";
 import { readMatter } from "./note-matter.mjs";
 import { scanFigures } from "./content-figures.mjs";
@@ -99,6 +100,8 @@ export function renderPreview(
     } catch (error) {
         findings.push({ file, severity: "warning", message: String(error.message) });
     }
+    for (const error of scanPageBreaks(body).errors)
+        findings.push({ file, severity: "error", ...error, line: bodyLine + error.line - 1 });
     applyComputedBeingAge(frontmatter, date);
     if (String(frontmatter.type ?? "").toLowerCase() === "being") {
         frontmatter.data ??= {};

package/engine/site-render.mjs

@@ -312,18 +312,30 @@ export function writeThemeFiles(out, staticDir = SITE_STATIC_DIR) {
  * @param {string} [options.staticDir] - The theme's own files, copied first.
  * @param {ReadonlySet<string>} [options.only] - The addresses of the pages to
  *   draw again into a site already written. Nothing else is touched.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {{files: string[], pages: string[], reachable: string[],
  *   findings: object[]}} Every file written, the address of every page, the
  *   address of each page reachable from the homepage, and the layouts' findings.
  * @throws {Error} When a page's address is outside the site, or a site served
  *   under a path asks for a sitemap index.
  */
-export function writeSite({ site, pages, out, report, staticDir = SITE_STATIC_DIR, only }) {
+export function writeSite({
+    site,
+    pages,
+    out,
+    report,
+    staticDir = SITE_STATIC_DIR,
+    only,
+    progress = () => {},
+}) {
     if (site.sitemaps && basePath(site) !== "/")
         throw new Error(
             `a sitemap index and robots.txt belong at the root of an origin, and this site is served under ${basePath(site)}`,
         );
     const tree = siteTree(site, pages);
+    progress(
+        `writing ${only ? tree.filter((page) => only.has(page.url)).length : tree.length} page(s)`,
+    );
     const published = new Set(tree.map((page) => page.url));
     const feedUrl = site.feed ? relUrl(site, `${site.feed.section}/atom.xml`) : "";
     const base = basePath(site);
@@ -659,6 +671,7 @@ export function deliverSiteFonts(config, out) {
  * @param {string} options.out - The directory the site is written to, which
  *   is the package's own directory under the deployed root.
  * @param {number} [options.year] - The year the footer states.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {Promise<{built: object, written: object|null, fonts: object|null,
  *   site?: object, pages?: object[], pageOf?: (entry: object) => object}>}
  *   What the build found, and, when it found nothing that stops it, what was
@@ -666,18 +679,19 @@ export function deliverSiteFonts(config, out) {
  *   becomes its page. `written` is `null` when a gate fired.
  * @throws {Error} When the site's settings or its cached menu cannot be read.
  */
-export async function buildPackageSite({ config, out, year }) {
+export async function buildPackageSite({ config, out, year, progress = () => {} }) {
     const settings = siteSettings({ config });
     const navigation = readCachedNavigation(config);
+    progress("indexing content");
     const sqlTables = await prepareTreeSqlTables(config.paths.content, {
         skipDirectories: config.skipDirectories,
         config,
         audience: "public",
     });
-    const built = buildSite({ config, sqlTables, write: false });
+    const built = buildSite({ config, sqlTables, progress });
     if (gatesFailed(built.gates)) return { built, written: null, fonts: null };
     const { site, pages, pageOf } = packageSite({ config, built, settings, navigation, year });
-    const written = writeSite({ site, pages, out });
+    const written = writeSite({ site, pages, out, progress });
     const fonts = deliverSiteFonts(config, out);
     return { built, written, fonts, site, pages, pageOf };
 }

package/engine/site-root.mjs

@@ -300,6 +300,7 @@ export async function indexSite({ site, output, base }) {
  *   `site.search` in the configuration. Default `true`.
  * @param {SiteIndexer} [options.indexer] - What builds it. Default
  *   {@link indexSite}.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {Promise<{files: string[], search: {dir: string, pages: number}|null}>}
  *   The files written, and the index — where it is and how many pages it
  *   holds — or `null` when none was built.
@@ -308,7 +309,14 @@ export async function indexSite({ site, output, base }) {
  *   under the prefix; or, located at the rendered site, when the indexer
  *   fails.
  */
-export async function writeSiteRoot({ pkg, base, out, search = true, indexer = indexSite }) {
+export async function writeSiteRoot({
+    pkg,
+    base,
+    out,
+    search = true,
+    indexer = indexSite,
+    progress = () => {},
+}) {
     const root = path.resolve(out);
     const prefix = base ?? `/${pkg}/`;
     const rendered = path.join(root, ...prefix.split("/").filter(Boolean));
@@ -331,6 +339,7 @@ export async function writeSiteRoot({ pkg, base, out, search = true, indexer = i
     }
     let pages;
     try {
+        progress("building the search index");
         ({ pages } = await indexer({ site: rendered, output: dir, base: prefix }));
     } catch (err) {
         const message = err instanceof Error ? err.message : String(err);

package/engine/site-serve-http.mjs

@@ -0,0 +1,151 @@
+/*
+ * 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
+ */
+
+/**
+ * HTTP stays responsive while the calling thread renders a large site.
+ * Only filesystem and listening addresses cross this boundary; the resolved
+ * configuration and the build's render closures remain with their caller.
+ * @module
+ */
+
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { parentPort, workerData } from "node:worker_threads";
+
+/** What a file is sent as, by its extension. */
+const CONTENT_TYPES = Object.freeze({
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".txt": "text/plain; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".wasm": "application/wasm",
+});
+
+/** The script a served page is sent with. */
+const RELOAD_SCRIPT = `<script>new EventSource(${JSON.stringify(workerData?.reloadPath)}).addEventListener("reload", () => location.reload());</script>`;
+
+if (parentPort) {
+    const { root, out, host, port, reloadPath: RELOAD_PATH } = workerData;
+    const listeners = new Set();
+    const server = http.createServer((req, res) => {
+        let address;
+        try {
+            address = decodeURIComponent(new URL(req.url ?? "/", "http://serve.invalid").pathname);
+        } catch {
+            res.writeHead(400, { "content-type": "text/plain; charset=utf-8" });
+            res.end("Bad request.\n");
+            return;
+        }
+        if (address === RELOAD_PATH) {
+            res.writeHead(200, {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            });
+            res.write(": connected\n\n");
+            listeners.add(res);
+            req.on("close", () => listeners.delete(res));
+            return;
+        }
+        if (!fs.existsSync(path.join(out, "index.html"))) {
+            res.writeHead(503, { "content-type": "text/plain; charset=utf-8", "retry-after": "1" });
+            res.end(
+                "No site is available yet. See build progress and diagnostics in the terminal.\n",
+            );
+            return;
+        }
+        let file = path.join(root, address);
+        if (file !== root && !file.startsWith(root + path.sep)) {
+            res.writeHead(403).end();
+            return;
+        }
+        if (fs.statSync(file, { throwIfNoEntry: false })?.isDirectory())
+            file = path.join(file, "index.html");
+        let status = 200;
+        if (!fs.existsSync(file)) {
+            status = 404;
+            file = path.join(out, "404.html");
+            if (!fs.existsSync(file)) {
+                res.writeHead(404).end();
+                return;
+            }
+        }
+        const type = CONTENT_TYPES[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+        let body = fs.readFileSync(file);
+        if (type.startsWith("text/html")) {
+            const html = body.toString("utf8");
+            const at = html.lastIndexOf("</body>");
+            body = Buffer.from(
+                at < 0 ? html + RELOAD_SCRIPT : html.slice(0, at) + RELOAD_SCRIPT + html.slice(at),
+            );
+        }
+        res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
+        res.end(body);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, resolve);
+    });
+    const listening = /** @type {import("node:net").AddressInfo} */ (server.address());
+    parentPort.postMessage({ kind: "listening", port: listening.port });
+
+    parentPort.on("message", (message) => {
+        if (message.kind === "reload") {
+            for (const res of listeners) res.write("event: reload\ndata: {}\n\n");
+        } else if (message.kind === "install") {
+            // Requests and these renames run on one event loop, so no request
+            // observes the gap between moving the old tree and installing it.
+            let moved = false;
+            try {
+                if (fs.existsSync(out)) {
+                    fs.renameSync(out, message.previous);
+                    moved = true;
+                }
+                try {
+                    fs.renameSync(message.staged, out);
+                } catch (error) {
+                    if (moved) {
+                        try {
+                            fs.renameSync(message.previous, out);
+                        } catch (rollback) {
+                            throw new Error(
+                                `the new site could not be installed or the previous one restored; the previous site remains at ${message.previous}`,
+                                { cause: rollback },
+                            );
+                        }
+                    }
+                    throw error;
+                }
+                parentPort.postMessage({ kind: "installed" });
+            } catch (error) {
+                parentPort.postMessage({ kind: "installed", error });
+            }
+        } else if (message.kind === "close") {
+            for (const res of listeners) res.end();
+            server.close(() => parentPort.close());
+            server.closeAllConnections();
+        }
+    });
+}