@heroiclands/package-build 23.12.5 → 23.12.7

package/engine/script-fonts.mjs

@@ -0,0 +1,172 @@
+/*
+ * 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
+ */
+
+/**
+ * **The faces a consumer installed.** `@heroiclands/fonts` owns the facts
+ * about its faces — family, class, direction, features and the code points
+ * each one draws — in its `fonts.json`, and this module reads them from the
+ * **consuming package's** install.
+ *
+ * package-build declares no dependency on `@heroiclands/fonts` in any field:
+ * the fonts package depends on package-build to build, so the consumer adds it
+ * as a devDependency of its own and package-build resolves it from the
+ * consumer's root. Resolving from this module's own location would find
+ * whatever happens to sit above package-build's install, or nothing.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/** The npm name of the fonts package. */
+export const FONTS_PACKAGE = "@heroiclands/fonts";
+
+/** The manifest the fonts package publishes at its root. */
+export const FONTS_MANIFEST = "fonts.json";
+
+/**
+ * One code point a face draws, as `fonts.json` lists it.
+ *
+ * @typedef {object} FaceCodepoint
+ * @property {string} codepoint - `U+` and the hexadecimal code point.
+ * @property {string} glyph - The glyph's name in the face.
+ * @property {string} kind - What it is: `letter`, `numeral`, `mark` and so on.
+ */
+
+/**
+ * One entry of `fonts.json`.
+ *
+ * @typedef {object} FontEntry
+ * @property {string} [name] - Its unique key; `family` when absent.
+ * @property {string} family - The CSS and Typst font family.
+ * @property {string} class - The class that sets text in it, `hl-<slug>`.
+ * @property {Record<string, string>} files - Its font files, by format.
+ * @property {string} direction - `ltr` or `rtl`.
+ * @property {string[]} features - OpenType features it turns on.
+ * @property {FaceCodepoint[]} [codepoints] - Every code point it draws.
+ */
+
+/**
+ * A face as a run reads it.
+ *
+ * @typedef {object} Face
+ * @property {string} slug - What `font=` names it by: its class without `hl-`.
+ * @property {string} family - The CSS and Typst font family.
+ * @property {string} class - The class that sets text in it.
+ * @property {string} direction - `ltr` or `rtl`.
+ * @property {string[]} features - OpenType features it turns on.
+ * @property {ReadonlySet<number>} draws - Every code point it draws.
+ */
+
+/**
+ * The installed fonts package, as a consumer sees it.
+ *
+ * @typedef {object} ScriptFonts
+ * @property {string} root - The package's directory.
+ * @property {string} version - Its `package.json` version.
+ * @property {{families: FontEntry[]}|undefined} manifest - Its `fonts.json`,
+ *   `undefined` when the installed version ships none.
+ * @property {Map<string, Face>} faces - Each face by its slug, in manifest
+ *   order; empty without a manifest.
+ */
+
+/**
+ * The slug `font=` names a face by: its class without the `hl-` prefix.
+ *
+ * @param {FontEntry} entry - A `fonts.json` entry.
+ * @returns {string|undefined} The slug, or `undefined` for an entry with no class.
+ */
+export function faceSlug(entry) {
+    const name = typeof entry?.class === "string" ? entry.class : "";
+    return name ? name.replace(/^hl-/, "") : undefined;
+}
+
+/**
+ * The code point a `U+XXXX` string names.
+ *
+ * @param {unknown} value - The listed code point.
+ * @returns {number|undefined} The code point, or `undefined` when it names none.
+ */
+function codepointOf(value) {
+    const match = /^U\+([0-9A-Fa-f]{4,6})$/.exec(String(value ?? ""));
+    return match ? Number.parseInt(match[1], 16) : undefined;
+}
+
+/**
+ * The fonts package the consumer at `rootDir` installed.
+ *
+ * @param {string} rootDir - The consuming package's root, holding its
+ *   `package.json`.
+ * @returns {ScriptFonts|undefined} The package, or `undefined` when the
+ *   consumer has not installed it.
+ * @throws {Error} When the installed `fonts.json` is not readable JSON, or
+ *   holds no `families` list.
+ */
+export function resolveScriptFonts(rootDir) {
+    const require = createRequire(path.join(rootDir, "package.json"));
+    let packageJson;
+    try {
+        packageJson = require.resolve(`${FONTS_PACKAGE}/package.json`);
+    } catch (err) {
+        if (/** @type {{code?: string}} */ (err)?.code === "MODULE_NOT_FOUND") return undefined;
+        throw err;
+    }
+    const root = path.dirname(packageJson);
+    const { version } = JSON.parse(fs.readFileSync(packageJson, "utf8"));
+
+    const manifestFile = path.join(root, FONTS_MANIFEST);
+    let manifest;
+    if (fs.existsSync(manifestFile)) {
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+        } catch (err) {
+            throw new Error(
+                `${manifestFile}: error: ${FONTS_PACKAGE} ${version} ships a ` +
+                    `${FONTS_MANIFEST} that is not readable JSON: ${/** @type {Error} */ (err).message}`,
+                { cause: err },
+            );
+        }
+        if (!Array.isArray(manifest?.families)) {
+            throw new Error(
+                `${manifestFile}: error: ${FONTS_PACKAGE} ${version} ships a ` +
+                    `${FONTS_MANIFEST} with no \`families\` list`,
+            );
+        }
+    }
+
+    const faces = new Map();
+    for (const entry of manifest?.families ?? []) {
+        const slug = faceSlug(entry);
+        if (!slug || faces.has(slug)) continue;
+        const draws = new Set();
+        for (const listed of entry.codepoints ?? []) {
+            const point = codepointOf(listed?.codepoint);
+            if (point !== undefined) draws.add(point);
+        }
+        faces.set(
+            slug,
+            Object.freeze({
+                slug,
+                family: entry.family,
+                class: entry.class,
+                direction: entry.direction === "rtl" ? "rtl" : "ltr",
+                features: Object.freeze([...(entry.features ?? [])]),
+                draws,
+            }),
+        );
+    }
+
+    return { root, version, manifest, faces };
+}

package/engine/site-build.mjs

@@ -65,6 +65,7 @@ import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { eventNoteIndex } from "./event-fields.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { renderSpans, scanSpans } from "./content-spans.mjs";
+import { renderRuns, runContext, scanRuns } from "./content-scripts.mjs";
 import { renderBlocks, renderWithheldSections, scanBlocks } from "./content-blocks.mjs";
 import { scanHeadingAttributes, withheldSections } from "./heading-attributes.mjs";
 import { renderFigureBlocks, scanFigures } from "./content-figures.mjs";
@@ -728,6 +729,7 @@ export function renderSitePage(
         figuresByAddress = new Map(),
         events,
         drawings = new Map(),
+        runs = runContext(config),
     },
 ) {
     const tableErrors = [];
@@ -879,9 +881,12 @@ export function renderSitePage(
     const authoredLinks = resolved.length;
     const resolvedBody =
         generated ? `${authoredBody}\n${protectCode(generated, resolve)}` : authoredBody;
-    const figured = renderFigureBlocks(resolvedBody, undefined, undefined, {
-        resolveRole: (address) => roleByWebSrc.get(address),
-    });
+    const figured = renderFigureBlocks(
+        renderRuns(resolvedBody, runs, undefined, { target: "site" }).markdown,
+        undefined,
+        undefined,
+        { resolveRole: (address) => roleByWebSrc.get(address) },
+    );
     for (const error of figureScan.errors)
         captionErrors.push({
             file: page.file,
@@ -893,6 +898,7 @@ export function renderSitePage(
         ...scanBlocks(page.body).errors,
         ...scanAlerts(page.body).errors,
         ...scanSpans(page.body).errors,
+        ...scanRuns(page.body, runs).errors,
         ...markupAnchorFindings(page.body),
     ])
         secretErrors.push({
@@ -1098,6 +1104,7 @@ export function renderPages(pages, options) {
             figuresByAddress,
             events,
             drawings: maps,
+            runs: runContext(config, records),
         });
         tableErrors.push(...result.tableErrors);
         expressionErrors.push(...result.expressionErrors);

package/engine/site-config.mjs

@@ -47,6 +47,7 @@ import { stringify as stringifyToml } from "smol-toml";
 
 import { checkHomepage, fail } from "../config.mjs";
 import { slugify } from "./content-slug.mjs";
+import { siteFontsParam } from "./script-font-delivery.mjs";
 
 /** The Hugo source directory, relative to the repository root. */
 export const HUGO_SOURCE = "build/hugo";
@@ -402,6 +403,10 @@ export function hugoConfig({ config, navigation, themesDir }) {
     if (config.site.assets) params.cdnBaseURL = config.site.assets;
     params.brand = { ...BRAND };
     if (config.site.notfound) params.notfound = structuredClone(config.site.notfound);
+    // Named only when the build copies the fonts, so the theme links nothing
+    // it does not ship.
+    const scriptFonts = siteFontsParam(config);
+    if (scriptFonts) params.scriptFonts = scriptFonts;
 
     const generated = {
         baseURL: config.homepage,

package/engine/site-root.mjs

@@ -111,16 +111,29 @@ export function noindexHeaders() {
 }
 
 /**
- * The `_headers` file's contents: the `noindex` rules, and nothing else.
+ * The `_headers` file's contents: the `noindex` rules, and the script fonts'
+ * cache rule when the site carries them.
  *
  * No `Cache-Control` is pinned on the prefix root. It is the homepage, and a
  * lifetime on it would hold a stale copy at the most-linked address after a
- * deploy; Pages' own defaults for a page apply.
+ * deploy; Pages' own defaults for a page apply. The fonts sit under a path
+ * that names their version, so a year's lifetime never serves a stale file.
  *
+ * @param {object} [options] - Options.
+ * @param {string} [options.pkg] - The content package, which is the prefix.
+ * @param {boolean} [options.fonts] - Whether the site carries the fonts.
  * @returns {string} The file's contents.
  */
-export function headers() {
-    return noindexHeaders().join("\n");
+export function headers({ pkg, fonts = false } = {}) {
+    const lines = noindexHeaders();
+    if (fonts && pkg) {
+        lines.push(
+            `/${pkg}/fonts/heroiclands/*`,
+            "  Cache-Control: public, max-age=31536000, immutable",
+            "",
+        );
+    }
+    return lines.join("\n");
 }
 
 /**
@@ -256,7 +269,8 @@ export async function writeSiteRoot({ pkg, out, search = true, indexer = indexSi
     }
 
     const file = path.join(root, "_headers");
-    fs.writeFileSync(file, headers());
+    const fonts = fs.existsSync(path.join(rendered, "fonts", "heroiclands"));
+    fs.writeFileSync(file, headers({ pkg, fonts }));
     fs.rmSync(path.join(root, "_redirects"), { force: true });
 
     const dir = path.join(rendered, SEARCH_DIR);

package/engine/sql-tables.mjs

@@ -31,9 +31,12 @@ import { collectAnchors } from "./anchors.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { NOTE_VOCABULARY, isGmNote } from "./note-vocabulary.mjs";
 import { encodeAddresses, flattenPublishedAddresses } from "./address-values.mjs";
-import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventRows } from "./event-rows.mjs";
+import { EVENT_COLUMNS, EVENT_SORT_COLUMNS, eventCalendars, eventRows } from "./event-rows.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
 import { NAME_COLUMNS, namesRows } from "./name-rows.mjs";
+import { RUN_COLUMNS, ownerOf, runsRows } from "./run-rows.mjs";
+import { MAP_COLUMNS, mapRows } from "./text-maps.mjs";
+import { NATIVE_COLUMNS, nativeRows } from "./map-lexicon.mjs";
 import {
     GLOSSARY_COLUMNS,
     AFFIX_COLUMNS,
@@ -276,6 +279,8 @@ export async function openNotesDatabase(
     await createRelations(connection, jsonl, encoded, "", audience);
     await createEventRelation(connection, path.join(base, "events.jsonl"), encoded, "", audience);
     await createNameRelation(connection, path.join(base, "names.jsonl"), encoded, "", audience);
+    await createRunRelation(connection, path.join(base, "runs.jsonl"), encoded, "", audience);
+    await createMapRelation(connection, path.join(base, "maps.jsonl"), encoded, "", audience);
     await createWordRelations(connection, path.join(base, "notes"), encoded, "", audience);
 
     // One schema per declared dependency, so `FROM sohl.notes` reads the notes
@@ -312,6 +317,20 @@ export async function openNotesDatabase(
             `${schema}.`,
             audience,
         );
+        await createRunRelation(
+            connection,
+            flat.replace(/\.jsonl$/, "-runs.jsonl"),
+            depRecords,
+            `${schema}.`,
+            audience,
+        );
+        await createMapRelation(
+            connection,
+            flat.replace(/\.jsonl$/, "-maps.jsonl"),
+            depRecords,
+            `${schema}.`,
+            audience,
+        );
         await createWordRelations(
             connection,
             flat.replace(/\.jsonl$/, ""),
@@ -346,6 +365,8 @@ export async function openNotesDatabase(
     for (const relation of [
         "events",
         "names",
+        "runs",
+        "maps",
         "words",
         "affixes",
         "fields",
@@ -552,7 +573,7 @@ async function createRelations(connection, file, records, prefix = "", audience
  */
 async function createEventRelation(connection, file, records, prefix, audience) {
     const visible = audience === "public" ? records.filter((record) => !isGmNote(record)) : records;
-    const rows = eventRows(visible, reckoningContext({ notes: records }));
+    const rows = eventRows(visible, reckoningContext({ notes: records }), eventCalendars(records));
     if (!rows.length) {
         const columns = EVENT_COLUMNS.map((column) => {
             const type = EVENT_SORT_COLUMNS.includes(column) ? "DOUBLE" : "VARCHAR";
@@ -564,7 +585,13 @@ async function createEventRelation(connection, file, records, prefix, audience)
         return;
     }
     fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n"));
-    await createTableFromFile(connection, `${prefix}events`, readJsonAuto(file));
+    // `whenIn` and `untilIn` are keyed by calendar Address, and read as structs
+    // whatever their number of keys, so `whenIn['<calendar>']` always binds.
+    await createTableFromFile(
+        connection,
+        `${prefix}events`,
+        readJsonAuto(file).replace(/\)$/, ", map_inference_threshold=-1)"),
+    );
 }
 
 /**
@@ -602,6 +629,95 @@ async function createNameRelation(connection, file, records, prefix, audience) {
     );
 }
 
+/**
+ * Create the `runs` relation: one row per span, div and poetry fence an own
+ * note marks with `lang=`, `font=` or `map=`, with the columns
+ * {@link module:engine/run-rows.RUN_COLUMNS} names. The columns are declared
+ * rather than inferred, so every value stays a string and none becomes a
+ * struct key whose case DuckDB folds.
+ *
+ * @param {object} connection - An open DuckDB connection.
+ * @param {string} file - Where to write the rows.
+ * @param {object[]} records - Index records, every Address a string.
+ * @param {string} prefix - A schema to qualify the relation name with.
+ * @param {"all"|"public"} audience - Whether to leave out GM notes.
+ * @returns {Promise<void>}
+ */
+async function createRunRelation(connection, file, records, prefix, audience) {
+    const rows = runsRows(
+        audience === "public" ? records.filter((record) => !isGmNote(record)) : records,
+    );
+    await createTypedRelation(connection, file, `${prefix}runs`, rows, RUN_COLUMNS, [
+        "line",
+        "column",
+    ]);
+}
+
+/**
+ * Create the `maps` relation: one row per row of a mapping note's
+ * `data.map`, with the columns {@link module:engine/text-maps.MAP_COLUMNS}
+ * names; and the `natives` relation, one row per native form of a language's
+ * word, with the columns {@link module:engine/map-lexicon.NATIVE_COLUMNS}
+ * names. A row is a row here, never a struct key, so `A` and `a` are two rows.
+ *
+ * @param {object} connection - An open DuckDB connection.
+ * @param {string} file - Where to write the rows.
+ * @param {object[]} records - Index records, every Address a string.
+ * @param {string} prefix - A schema to qualify the relation name with.
+ * @param {"all"|"public"} audience - Whether to leave out GM notes.
+ * @returns {Promise<void>}
+ */
+async function createMapRelation(connection, file, records, prefix, audience) {
+    const rows = mapRows(
+        audience === "public" ? records.filter((record) => !isGmNote(record)) : records,
+        ownerOf,
+    );
+    await createTypedRelation(connection, file, `${prefix}maps`, rows, MAP_COLUMNS, ["row"]);
+    const visible = audience === "public" ? records.filter((record) => !isGmNote(record)) : records;
+    await createTypedRelation(
+        connection,
+        file.replace(/maps\.jsonl$/, "natives.jsonl"),
+        `${prefix}natives`,
+        nativeRows(visible),
+        NATIVE_COLUMNS,
+        ["word", "native"],
+    );
+}
+
+/**
+ * Create a relation whose columns are declared rather than inferred, so every
+ * value stays a string or a number and none becomes a struct key whose case
+ * DuckDB folds. An empty relation keeps its columns.
+ *
+ * @param {object} connection - An open DuckDB connection.
+ * @param {string} file - Where to write the rows.
+ * @param {string} name - The relation, schema-qualified where it is a dependency's.
+ * @param {object[]} rows - Its rows.
+ * @param {readonly string[]} columns - Its columns, in order.
+ * @param {readonly string[]} integers - The columns that are `BIGINT`; the
+ *   rest are `VARCHAR`.
+ * @returns {Promise<void>}
+ */
+async function createTypedRelation(connection, file, name, rows, columns, integers) {
+    const columnTypes = columns.map((column) => [
+        column,
+        integers.includes(column) ? "BIGINT" : "VARCHAR",
+    ]);
+    if (!rows.length) {
+        const nulls = columnTypes.map(([column, type]) => `NULL::${type} AS "${column}"`);
+        await connection.run(`CREATE VIEW ${name} AS SELECT ${nulls.join(", ")} WHERE false`);
+        return;
+    }
+    fs.writeFileSync(file, rows.map((row) => JSON.stringify(row)).join("\n"));
+    const schema = columnTypes.map(([column, type]) => `'${column}': '${type}'`).join(", ");
+    await createTableFromFile(
+        connection,
+        name,
+        `SELECT * FROM read_json('${file.replace(/'/g, "''")}', columns={${schema}}, ` +
+            "format='newline_delimited', maximum_object_size=20000000)",
+    );
+}
+
 /**
  * Create a relation as a table, so the JSONL behind it is parsed once when the
  * database opens rather than on every query. A view over `read_json_auto`
@@ -693,7 +809,7 @@ async function createWordRelations(connection, stem, records, prefix, audience)
         senses: "STRUCT(text VARCHAR, bodies VARCHAR[])[]",
         usage: "VARCHAR[]",
         depth: "BIGINT",
-        verbs: `STRUCT(invariant BOOLEAN, persons STRUCT(${VERB_PERSON_FIELDS.map((person) => `"${person.name}" VARCHAR`).join(", ")}))`,
+        verbs: `STRUCT(invariant BOOLEAN, replaces VARCHAR, persons STRUCT(${VERB_PERSON_FIELDS.map((person) => `"${person.name}" VARCHAR`).join(", ")}))`,
     };
     const dictionaryFile = `${stem}-dictionary.jsonl`;
     if (dictionary.length) {