@heroiclands/package-build 23.13.0 → 24.0.0

package/engine/pdf-render.mjs

@@ -36,7 +36,7 @@
  * ## Links, and the one rule that decides them
  *
  * A wikilink is already resolved to a URL before this module sees it — by the
- * same {@link module:engine/web-wikilinks} pass the site uses, so the two
+ * same {@link module:engine/wikilinks} resolver the site uses, so the two
  * surfaces cannot disagree about where a link points. What differs is what a
  * *book* does with the answer:
  *
@@ -61,19 +61,10 @@
  * @module
  */
 
-import MarkdownIt from "markdown-it";
-import footnotePlugin from "markdown-it-footnote";
-import deflistPlugin from "markdown-it-deflist";
-
+import { createRenderer } from "./content-render.mjs";
 import { bookDraftNoticePreamble } from "./draft-notice.mjs";
-import { iconPlugin, ICON_PATTERN, ICON_SIZES } from "./content-icons.mjs";
-import {
-    IMAGE_CLASSES,
-    IMAGE_FLOATS,
-    IMAGE_PATTERN,
-    checkImages,
-    imagePlugin,
-} from "./content-images.mjs";
+import { ICON_PATTERN, ICON_SIZES } from "./content-icons.mjs";
+import { IMAGE_CLASSES, IMAGE_FLOATS, IMAGE_PATTERN, checkImages } from "./content-images.mjs";
 import { bookImageWidthIn } from "./pdf-images.mjs";
 import { CHRONOLOGY_SLUG } from "./generated-sections.mjs";
 
@@ -89,15 +80,14 @@ export const BOOK_IMAGE_WIDTHS = Object.freeze({
 import { markupAnchorFindings } from "./anchors.mjs";
 import { indexChapter, indexMarker, indexPreamble } from "./pdf-index.mjs";
 import { slugify } from "./content-slug.mjs";
-import { alertMarkdownPlugin, scanAlerts, ALERT_TYPES } from "./content-alerts.mjs";
-import { spanMarkdownPlugin, scanSpans } from "./content-spans.mjs";
+import { scanAlerts, ALERT_TYPES } from "./content-alerts.mjs";
+import { scanSpans } from "./content-spans.mjs";
 import { GENERIC_FONTS, renderRuns, scanRuns } from "./content-scripts.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { BLOCK_CONTAINERS, scanBlocks, BLOCK_NAMES } from "./content-blocks.mjs";
 import {
     COLUMNS_CLASS,
     STANZA_BREAK,
-    inlineVerse,
     lineNumber,
     rightToLeft,
     scanVerse,
@@ -107,6 +97,8 @@ import {
 import { matchAllOutsideCode, replaceOutsideCode } from "./code-fences.mjs";
 import { HTML_TAG, htmlMessage } from "./content-html.mjs";
 import { EXPRESSION } from "./markdown-expressions.mjs";
+import { inlineText } from "./name-markup.mjs";
+import { cartouchePathname, glyphPathname, humanizeSlug, typstLength } from "./content-glyphs.mjs";
 import { WIKILINK } from "./wikilink-syntax.mjs";
 import { EMBED_PATTERN } from "./content-embeds.mjs";
 import { positionInBody } from "./diagnostics.mjs";
@@ -197,43 +189,22 @@ export function labelFor(anchor) {
 }
 
 /**
- * A markdown-it configured to parse, not to render.
+ * The shared parser configured for the book: the `book` target of
+ * {@link module:engine/content-render.createRenderer}, which parses and leaves
+ * the output to this module's Typst stage.
  *
  * `html: false` is the load-bearing setting: raw HTML in a note has no route to
  * Typst at all, which is why {@link module:engine/content-html} reports it. With
  * HTML disabled markdown-it emits the tag as text, so it arrives in the book
- * visibly wrong rather than invisibly missing.
+ * visibly wrong rather than invisibly missing. The one tag it reads is the
+ * emphasis a script run's convention sets, which the run's rewrite writes and
+ * the book prints in its rubric ink or under an overline.
  *
  * @param {object} [registry] - The icon registry.
  * @returns {object} A markdown-it instance.
  */
 export function createParser(registry) {
-    const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
-    md.use(footnotePlugin);
-    md.use(alertMarkdownPlugin);
-    md.use(spanMarkdownPlugin);
-    // Verse is held inside a literal fence. Parse its inline content before
-    // footnote_tail collects definitions, using the surrounding note's env.
-    md.core.ruler.after("inline", "verse_inline", (state) => {
-        for (const token of state.tokens) {
-            if (token.type !== "fence" || !/^verse(?:\s|$)/.test(token.info?.trim() || ""))
-                continue;
-            token.meta ??= {};
-            token.meta.verseStanzas = verseStanzas(token.content).map((stanza) =>
-                stanza.map(({ text, level }) => {
-                    const children = [];
-                    state.md.inline.parse(inlineVerse(text), state.md, state.env, children);
-                    return { children, level };
-                }),
-            );
-        }
-    });
-    md.use(deflistPlugin);
-    md.use(iconPlugin(registry));
-    // The same plugin the HTML surfaces use, so one directive is read once and
-    // three renderers read the same `meta` off the same token.
-    md.use(imagePlugin());
-    return md;
+    return createRenderer("book", { icons: registry }).md;
 }
 
 /**
@@ -1385,6 +1356,12 @@ function renderInline(token, ctx) {
                 out.push(inlineRaw(child.content));
                 break;
             case "span_open": {
+                const sign = renderGlyph(children, i, ctx) ?? renderCartouche(children, i, ctx);
+                if (sign) {
+                    out.push(sign.typst);
+                    i = sign.close;
+                    break;
+                }
                 // Inline secrecy has no print presentation; other classes and ids survive.
                 const classes = (child.attrGet?.("class") ?? "")
                     .split(/\s+/)
@@ -1419,6 +1396,16 @@ function renderInline(token, ctx) {
                 out.push(`]${id ? ` <${sectionLabel(ctx.anchorPrefix, id)}>` : ""}`);
                 break;
             }
+            case "script_emphasis_open":
+                out.push(
+                    child.meta?.convention === "rubric" ?
+                        "#text(fill: book-rubric)["
+                    :   "#overline[",
+                );
+                break;
+            case "script_emphasis_close":
+                out.push("]");
+                break;
             case "strong_open":
                 out.push("#strong[");
                 break;
@@ -1473,6 +1460,74 @@ function renderInline(token, ctx) {
     return out.join("");
 }
 
+/**
+ * A glyph span as the picture the book carries, or as its label when the
+ * package ships no file for it.
+ *
+ * @param {object[]} children - Inline children.
+ * @param {number} i - The index of a `span_open`.
+ * @param {object} ctx - Render context.
+ * @returns {{typst: string, close: number}|undefined} The Typst and the index
+ *   of the closing token; `undefined` when the span is not a well-formed glyph.
+ */
+function renderGlyph(children, i, ctx) {
+    const open = children[i];
+    const classes = (open.attrGet?.("class") ?? "").split(/\s+/);
+    const slug = open.attrGet?.("slug");
+    if (!classes.includes("glyph") || !slug || open.meta?.problems?.length) return undefined;
+    const close = childMatching(children, i, "span_open", "span_close");
+    const label = inlineText(children.slice(i + 1, close)).trim() || humanizeSlug(slug);
+    const staged = ctx.images.get(glyphPathname(slug));
+    if (!staged) return { typst: escapeTypst(label), close };
+    const picture = `image("${escapeTypstString(staged)}", height: 1.8em)`;
+    const frame = open.attrGet?.("frame");
+    const typst =
+        frame === "tablet" ?
+            `#box(fill: rgb("#ece1c8"), inset: (x: 0.3em, y: 0.15em), radius: 0.2em, baseline: 25%, ${picture})`
+        : open.attrGet?.("size") === "block" ? `#align(center, ${picture})`
+        : `#box(baseline: 25%, ${picture})`;
+    return { typst, close };
+}
+
+/**
+ * A cartouche span as the figure the book prints. Print cannot wrap text
+ * around it, so `align` places the figure between the lines of its sentence.
+ *
+ * @param {object[]} children - Inline children.
+ * @param {number} i - The index of a `span_open`.
+ * @param {object} ctx - Render context.
+ * @returns {{typst: string, close: number}|undefined} The Typst and the index
+ *   of the closing token; `undefined` when the span is not a well-formed
+ *   cartouche.
+ */
+function renderCartouche(children, i, ctx) {
+    const open = children[i];
+    const classes = (open.attrGet?.("class") ?? "").split(/\s+/);
+    const slug = open.attrGet?.("slug");
+    if (!classes.includes("cartouche") || !slug || open.meta?.problems?.length) return undefined;
+    const close = childMatching(children, i, "span_open", "span_close");
+    const align = open.attrGet?.("align");
+    const height = open.attrGet?.("height");
+    const caption = open.attrGet?.("caption");
+    const alt = inlineText(children.slice(i + 1, close)).trim();
+    const staged = ctx.images.get(cartouchePathname(slug));
+    const label = caption ? escapeTypst(caption) : "";
+    const text = (content) => `#text(size: 7.6pt, style: "italic", fill: luma(45%))[${content}]`;
+    if (!staged) {
+        const shown = label || escapeTypst(alt || humanizeSlug(slug));
+        return { typst: `\n#align(center, ${text(shown)})\n`, close };
+    }
+    const size =
+        height ? typstLength(height)
+        : align ? "7em"
+        : "10em";
+    const picture = `image("${escapeTypstString(staged)}", height: ${size})`;
+    return {
+        typst: `\n#align(${align ?? "center"}, block(breakable: false)[#${picture}${label ? ` \\ ${text(label)}` : ""}])\n`,
+        close,
+    };
+}
+
 /**
  * The index of the inline token closing the one at `i`.
  *
@@ -1890,6 +1945,9 @@ export function bookTypstPreamble(runs = {}, families = {}) {
         // run to the trimmed edge of the paper.
         "#let book-title-measure = book-text-width - 2.5cm",
         '#let book-ink = rgb("#241f1a")',
+        // A rubric script's emphasis: a vermilion that holds 4.5:1 on the paper
+        // and stays apart from the ink in lightness.
+        '#let book-rubric = rgb("#9c281b")',
         '#let book-paper = rgb("#f4efe4")',
         '#let book-accent = rgb("#7c3b1e")',
         '#let book-head = rgb("#5e2b14")',

package/engine/post-fields.mjs

@@ -0,0 +1,157 @@
+/*
+ * 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
+ */
+
+/**
+ * **A blog post** is a `doc` of `subType: post`. It states the day it was
+ * published in `data.date`, as `YYYY-MM-DD`, and may name its writer in
+ * `data.author`; a post that names none carries the site's byline, the first
+ * entry of `authors`. Its `tags` are the top-level ones any note carries.
+ *
+ * Both fields belong to a post alone. {@link checkPostFields} requires the date
+ * on a post, refuses either field on any other `doc`, and refuses a date that
+ * is not a calendar day or an author that is blank.
+ *
+ * @module
+ */
+
+import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/** The `doc` subType a post is. */
+export const POST_SUBTYPE = "post";
+
+/** A calendar day as a post states it. */
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/**
+ * Whether a note's frontmatter, or a page's parameters, are a post's.
+ *
+ * @param {{type?: unknown, subType?: unknown}|null|undefined} fm - The frontmatter.
+ * @returns {boolean} Whether it is a `doc` of `subType: post`.
+ */
+export function isPost(fm) {
+    return (
+        String(fm?.type ?? "").toLowerCase() === "doc" &&
+        String(fm?.subType ?? "").toLowerCase() === POST_SUBTYPE
+    );
+}
+
+/**
+ * Whether a string is a calendar day, `YYYY-MM-DD`, that exists.
+ *
+ * @param {unknown} value - The value.
+ * @returns {boolean} Whether it is one.
+ */
+export function isCalendarDay(value) {
+    if (typeof value !== "string") return false;
+    const match = DAY.exec(value);
+    if (!match) return false;
+    const [year, month, day] = match.slice(1).map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (
+        date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day
+    );
+}
+
+/** `data.date`, as the vocabulary declares it. */
+export const POST_DATE_FIELD = Object.freeze({
+    name: "date",
+    shape: "string",
+    kind: "string",
+    describe:
+        "The day a post was published, as `YYYY-MM-DD`. Required on a `post`; no other " +
+        "subType states it. Posts are listed and fed newest first by it.",
+});
+
+/** `data.author`, as the vocabulary declares it. */
+export const POST_AUTHOR_FIELD = Object.freeze({
+    name: "author",
+    shape: "string",
+    kind: "string",
+    describe:
+        "Who wrote a post, as the byline prints them. A post that names none carries the " +
+        "site's byline, the first entry of `authors`; no other subType states it.",
+});
+
+/**
+ * Scope `data.date` and `data.author` to posts, and check their values.
+ *
+ * A post with no date is an error at its `subType:` line; a date that is not a
+ * calendar day, or an author that is blank, is an error at the value. Either
+ * field on a `doc` that is not a post is an error at the key.
+ *
+ * @param {object} note - The note, as the link index hands it over.
+ * @returns {object[]} Findings.
+ */
+export function checkPostFields(note) {
+    const type = String(note?.type ?? note?.fm?.type ?? "").toLowerCase();
+    if (type !== "doc") return [];
+    const raw = note.raw ?? "";
+    const data = note?.fm?.data;
+    const has = (key) =>
+        data !== null &&
+        typeof data === "object" &&
+        !Array.isArray(data) &&
+        data[key] !== undefined &&
+        data[key] !== null;
+    const finding = (keyPath, message, key = false) => ({
+        file: note.file,
+        ...positionOfFrontmatterPath(raw, keyPath, { key }),
+        severity: "error",
+        message,
+    });
+
+    if (!isPost({ type, subType: note?.fm?.subType })) {
+        return ["date", "author"]
+            .filter(has)
+            .map((key) =>
+                finding(
+                    ["data", key],
+                    `\`data.${key}\` is stated by a post, and this note's \`subType\` is not ` +
+                        `\`${POST_SUBTYPE}\``,
+                    true,
+                ),
+            );
+    }
+
+    const findings = [];
+    if (!has("date")) {
+        findings.push({
+            file: note.file,
+            ...positionInFrontmatter(raw, "subType", undefined, { topLevel: true }),
+            severity: "error",
+            message:
+                "a post is listed and fed by the day it was published, so it must state " +
+                "`data.date`, as `YYYY-MM-DD`",
+        });
+    } else if (typeof data.date === "string" && !isCalendarDay(data.date)) {
+        findings.push(
+            finding(
+                ["data", "date"],
+                `\`data.date\` is \`${String(data.date)}\`, which is not a calendar day written ` +
+                    "`YYYY-MM-DD`",
+            ),
+        );
+    }
+    if (has("author") && typeof data.author === "string" && !data.author.trim()) {
+        findings.push(
+            finding(
+                ["data", "author"],
+                "`data.author` names who wrote the post; leave it out for the site's byline " +
+                    "rather than writing it blank",
+            ),
+        );
+    }
+    return findings;
+}

package/engine/preview-index.mjs

@@ -0,0 +1,130 @@
+/*
+ * 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
+ */
+
+/**
+ * **What an editor with a content index gives the preview.** {@link previewIndex}
+ * turns a package's configuration and its content-index records into the one
+ * object {@link module:engine/site-preview.renderPreview} takes as `index`. A
+ * preview given it resolves links, embeds, marked text, icons and figure
+ * numbers as the website does; a preview without one shows the buffer's source.
+ *
+ * Build it once per index and reuse it for every render: it holds the link
+ * index, the asset address space, the languages' maps and the events of every
+ * note.
+ *
+ * @module
+ */
+
+import { addressSlug } from "./content-address.mjs";
+import { expandContent } from "./content-expand.mjs";
+import { embedRole } from "./content-embeds.mjs";
+import { renderImageFigures } from "./content-images.mjs";
+import { runContext } from "./content-scripts.mjs";
+import { eventNoteIndex } from "./event-fields.mjs";
+import { isHomepage } from "./homepage.mjs";
+import { authoredFrontmatter, isNoteRecord, isStub } from "./index-records.mjs";
+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 { siteBase } from "../content-config.mjs";
+
+/**
+ * What a preview reads to render with an index.
+ *
+ * @typedef {object} PreviewIndex
+ * @property {object} runs - The package's languages, faces and maps.
+ * @property {object|undefined} icons - The package's icon registry.
+ * @property {(src: string) => ({role?: string, width?: number|"", height?: number|""}|undefined)} lookupAsset -
+ *   From a picture's address to its asset.
+ * @property {(src: string) => string} resolveSrc - From a picture's authored
+ *   pathname to the address the website serves it at.
+ * @property {(markdown: string, note: {fm: object, file?: string}) => {markdown: string, figures: object[]}} expand -
+ *   Expand a buffer's body as the website expands a page: links, embeds,
+ *   expressions and figure numbers resolved. A query, which a buffer cannot
+ *   answer, is left as written.
+ */
+
+/**
+ * Build the object a preview with an index renders from.
+ *
+ * @param {object} options
+ * @param {object} options.config - The resolved package configuration.
+ * @param {object[]} options.records - The content index's records: every note
+ *   and every asset.
+ * @param {object} [options.foreign] - The dependencies' indexes, as
+ *   {@link module:engine/metadata-index.loadForeignIndexes} returns them.
+ *   Omitted, the package links only to itself.
+ * @returns {PreviewIndex} The index.
+ */
+export function previewIndex({ config, records, foreign }) {
+    const base = siteBase(config);
+    const entries = [];
+    for (const record of records) {
+        if (!isNoteRecord(record) || isStub(record)) continue;
+        const fm = authoredFrontmatter(record);
+        if (isGmNote(fm) || typeof fm.shortcode !== "string" || !fm.shortcode) continue;
+        entries.push({
+            kind: "content",
+            fm,
+            body: "",
+            anchors: record.anchors ?? [],
+            pkg: record.package ?? config.contentPackage,
+            name: fm.name?.full ?? fm.shortcode,
+            url: isHomepage(fm) ? base : `${base}${addressSlug(fm)}/`,
+        });
+    }
+    const site = buildSiteIndex(entries, {
+        package: config.contentPackage,
+        currentDate: config.currentDate,
+        foreignIndex: foreign?.index,
+        foreignReferences: foreign?.references,
+        records,
+        noIndexPackages: noContentIndexPackages(config),
+    });
+    const assets = assetAddressIndex(records, { config, foreign, types: site.contentTypes });
+    const events = eventNoteIndex(records, {
+        contentPackage: site.contentPackage,
+        foreignIndex: foreign?.index,
+        dates: site.dateContext,
+    });
+    const resolveRole = (address) => embedRole(assets, address);
+    const webSrc = (src) =>
+        pathnameProblem(src) ? src : (resolvePathname(src, config)?.web ?? src);
+    const lookupAsset = (src) => {
+        const key = assetPathnameKey(src, config);
+        return key ? assets?.byPath?.get(key) : undefined;
+    };
+    return {
+        runs: runContext(config, records),
+        icons: config.icons,
+        lookupAsset,
+        resolveSrc: webSrc,
+        expand: (markdown, { fm, file }) => {
+            const expanded = expandContent(markdown, {
+                target: "web",
+                index: site,
+                note: { fm, file, source: file || "<buffer>" },
+                events,
+                resolveRole,
+                links: {
+                    foreign: foreign?.index,
+                    assets,
+                    afterLinks: (block) => renderImageFigures(block, webSrc, lookupAsset),
+                },
+            });
+            return { markdown: expanded.markdown, figures: expanded.figures.figures };
+        },
+    };
+}