@heroiclands/package-build 23.12.6 → 23.12.7

package/engine/markup-validation.mjs

@@ -13,6 +13,7 @@
 
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanAlerts } from "./content-alerts.mjs";
+import { scanRuns } from "./content-scripts.mjs";
 
 /**
  * Validate authored block syntax with positions in the original file.
@@ -20,20 +21,33 @@ import { scanAlerts } from "./content-alerts.mjs";
  * @param {string} source - Complete Markdown source, optionally with frontmatter.
  * @param {string} file - Diagnostic filename.
  * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Exact-text scanner projections.
- * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
+ * @param {import("./content-scripts.mjs").RunContext} [runs] - The package's
+ *   languages, faces and maps. Given, text marked with `lang=`, `font=` and
+ *   `map=` is checked against them; a caller with no package configuration
+ *   leaves it out.
+ * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors,
+ *   then warnings.
  */
-export function markupFindings(source, file, syntax) {
+export function markupFindings(source, file, syntax, runs) {
     const body = String(source ?? "").replace(
         /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,
         (frontmatter) => frontmatter.replace(/[^\r\n]/g, " "),
     );
     const scanned = syntax?.(body);
-    return [
+    const marked = runs ? scanRuns(body, runs, syntax) : undefined;
+    const errors = [
         ...(scanned?.blocks ?? scanBlocks(body)).errors,
         ...(scanned?.alerts ?? scanAlerts(body)).errors,
+        ...(marked?.errors ?? []),
     ].map((error) => ({
         file,
         ...error,
         severity: "error",
     }));
+    const warnings = (marked?.warnings ?? []).map((warning) => ({
+        file,
+        ...warning,
+        severity: "warning",
+    }));
+    return [...errors, ...warnings];
 }

package/engine/names.mjs

@@ -19,8 +19,8 @@ import { formatLocator } from "./diagnostics.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { isNoteRecord } from "./index-records.mjs";
 import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { WORD } from "./word-pattern.mjs";
 
-const WORD = /[\p{L}\p{M}\p{N}]+(?:[’'–-][\p{L}\p{M}\p{N}]+)*/gu;
 const compare = (a, b) =>
     a < b ? -1
     : a > b ? 1

package/engine/note-vocabulary.mjs

@@ -153,6 +153,7 @@ import { checkCitedPopulations, checkPopulation } from "./populations.mjs";
 import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkSettlementTables } from "./settlement-tables.mjs";
+import { checkMapField } from "./text-maps.mjs";
 
 /**
  * One `data:` key a note type may carry.
@@ -1514,6 +1515,47 @@ export const BEING_ARCHETYPES = Object.freeze({
     guildsperson: "Has professional training, standing, or connections that open doors.",
 });
 
+/**
+ * One row of a mapping note's `data.map.rows` or of a face's own `rows`.
+ *
+ * @type {object}
+ */
+const MAP_ROW_ENTRY = Object.freeze({
+    kind: "list-or-map",
+    shape: "`[from, to]` or `{ from, to, before?, at? }`",
+    entries: Object.freeze({ ...TEXT, shape: "a string" }),
+    fields: Object.freeze([
+        {
+            name: "from",
+            ...TEXT,
+            shape: "a string of one or more characters",
+            required: true,
+            describe: "The one or more characters the row matches.",
+        },
+        {
+            name: "to",
+            ...TEXT,
+            shape: "a string, which may be empty",
+            required: true,
+            allowEmpty: true,
+            describe: "What the row writes in their place; empty to drop them.",
+        },
+        {
+            name: "before",
+            ...TEXT,
+            allowed: Object.freeze(["vowel", "consonant"]),
+            describe:
+                "`vowel` or `consonant`: what must follow the match for the " + "row to apply.",
+        },
+        {
+            name: "at",
+            ...TEXT,
+            allowed: Object.freeze(["start", "end"]),
+            describe: "`start` or `end`: where the match must sit for the row to " + "apply.",
+        },
+    ]),
+});
+
 /**
  * Every note type this toolchain compiles, and the closed vocabulary it
  * declares.
@@ -2148,6 +2190,77 @@ export const NOTE_VOCABULARY = Object.freeze({
                     "The culture a setting guide introduces, as a culture lore note. " +
                     "Required on `settingguide`; no other subType states it.",
             },
+            {
+                name: "map",
+                kind: "map",
+                shape: "a map — `{ name, vowels?, fonts, rows }`",
+                check: checkMapField,
+                fields: Object.freeze([
+                    {
+                        name: "name",
+                        ...TEXT,
+                        required: true,
+                        describe:
+                            "What `map=` names the map by: lowercase letters, digits and `-`, " +
+                            "unique in the package.",
+                    },
+                    {
+                        name: "vowels",
+                        ...TEXT,
+                        describe:
+                            "The characters a row's `before: vowel` reads as vowels; any other " +
+                            "letter is a consonant.",
+                    },
+                    {
+                        name: "rows",
+                        kind: "list",
+                        shape: "list of `[from, to]` or `{ from, to, before?, at? }`",
+                        required: true,
+                        entries: MAP_ROW_ENTRY,
+                        describe:
+                            "The rewrites, each `[from, to]` or `{ from, to, before?, at? }`: " +
+                            "`before` is `vowel` or `consonant`, `at` is `start` or `end`. The " +
+                            "longest `from` wins, and a character no row matches passes through.",
+                    },
+                    {
+                        name: "fonts",
+                        kind: "list",
+                        shape: "list of `{ font, rows? }`",
+                        required: true,
+                        entries: Object.freeze({
+                            kind: "map",
+                            shape: "a map — `{ font, rows? }`",
+                            fields: Object.freeze([
+                                {
+                                    name: "font",
+                                    ...TEXT,
+                                    required: true,
+                                    shape: "an installed face's slug",
+                                    describe:
+                                        "A face the map is drawn in, by the slug `font=` names it by.",
+                                },
+                                {
+                                    name: "rows",
+                                    kind: "list",
+                                    shape: "list of `[from, to]` or `{ from, to, before?, at? }`",
+                                    entries: MAP_ROW_ENTRY,
+                                    describe:
+                                        "Rows for this face alone, tried before the shared `rows`; " +
+                                        "the same shapes and conditions.",
+                                },
+                            ]),
+                        }),
+                        describe:
+                            "The faces the map is drawn in, at least one, each with any rows of " +
+                            "its own. A run in another face is refused, and each face must draw " +
+                            "every character its rows and the lexicon's native forms write.",
+                    },
+                ]),
+                describe:
+                    "A mapping, which text marked `map=` with its `name` is rewritten by " +
+                    "before it is set. See " +
+                    "[mapping notes](format-details.md#mapping-notes).",
+            },
         ]),
     }),
 

package/engine/pdf-build.mjs

@@ -81,6 +81,7 @@ import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 
 import { CONFIG_FILENAMES, loadPackConfig, packConfigPath } from "./pack-config.mjs";
+import { runContext } from "./content-scripts.mjs";
 import { routerFor } from "./pack-router.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { indexRecordsFor } from "./content-index.mjs";
@@ -160,6 +161,7 @@ import { resolveIconGlyphs } from "./pdf-fonts.mjs";
 import { drawMapsFrom } from "./derived-sections.mjs";
 import { generatedDrawing, markGenerated, splitGenerated } from "./generated-sections.mjs";
 import { resolveAssetReplacement } from "./asset-replacement.mjs";
+import { typstScriptFontPath } from "./script-font-delivery.mjs";
 
 /**
  * The file on disk an authored image pathname names, or `null`.
@@ -832,7 +834,7 @@ export async function buildPdf({
          *   message: string}} The table, or null with why it could not be read.
          */
         const measureAll = (written) => {
-            const fontArgs = typstFontArgs(resolved.pdf);
+            const fontArgs = typstFontArgs(resolved.pdf, resolved);
             const measured = new Map();
             for (const { entry } of toRender) {
                 const result = readPages(
@@ -906,7 +908,7 @@ export async function buildPdf({
             if (!wanted) continue;
             const result = pass.written.get(entry.id);
             imageReports.push(...(result.imageReports ?? []));
-            const ok = compile ? compileBook(result, resolved.pdf, findings) : true;
+            const ok = compile ? compileBook(result, resolved.pdf, findings, resolved) : true;
             if (!ok) built = false;
             books.push({
                 id: entry.id,
@@ -1616,6 +1618,7 @@ async function buildBook(book, shared) {
                 url: site,
                 elsewhere,
                 findings,
+                runs: runContext(resolved, records),
                 file: page.file,
                 bodyLine: page.bodyLine,
                 prepared: true,
@@ -1706,6 +1709,7 @@ async function buildBook(book, shared) {
                     elsewhere,
                     indexMentions: true,
                     findings,
+                    runs: runContext(resolved, records),
                     file,
                 }),
             );
@@ -1737,6 +1741,7 @@ async function buildBook(book, shared) {
                 elsewhere,
                 indexMentions: true,
                 findings,
+                runs: runContext(resolved, records),
                 file,
             });
         } catch {
@@ -1910,6 +1915,7 @@ async function buildBook(book, shared) {
         copyright: shared.copyright,
         license: shared.license,
         index,
+        runs: runContext(resolved, records),
     });
     // Last, over the whole document: a reference can only be checked once every
     // declaration is in one string, and Typst treats a dangling one as fatal.
@@ -1932,10 +1938,11 @@ async function buildBook(book, shared) {
  * @param {{typ: string, pdf: string}} written - From {@link buildBook}.
  * @param {object} pdf - The resolved `pdf:` block.
  * @param {object[]} findings - Collected here rather than thrown.
+ * @param {object} config - The resolved configuration.
  * @returns {boolean} Whether the PDF was written.
  */
-function compileBook(written, pdf, findings) {
-    const compiled = compileTypst(written.typ, written.pdf, pdf);
+function compileBook(written, pdf, findings, config) {
+    const compiled = compileTypst(written.typ, written.pdf, pdf, config);
     findings.push(...compiled.findings);
     if (!compiled.ok) {
         findings.push({ file: written.typ, severity: "error", message: compiled.message });
@@ -1979,10 +1986,13 @@ export const BOOK_FONTS_PATH = path.join(
  * @param {string} typPath - The `.typ` file.
  * @param {string} pdfPath - Where the PDF goes.
  * @param {object} [pdf] - The resolved `pdf:` block.
+ * @param {{rootDir?: string, paths?: {content?: string}}} [config] - The
+ *   resolved configuration; the installed faces are searched when a note sets
+ *   text in one.
  * @returns {string[]} The arguments, in order.
  */
-export function typstArgs(typPath, pdfPath, pdf = {}) {
-    return ["compile", ...typstFontArgs(pdf), typPath, pdfPath];
+export function typstArgs(typPath, pdfPath, pdf = {}, config) {
+    return ["compile", ...typstFontArgs(pdf, config), typPath, pdfPath];
 }
 
 /**
@@ -1990,14 +2000,20 @@ export function typstArgs(typPath, pdfPath, pdf = {}) {
  * the page measurement so both lay the book out in the same metrics.
  *
  * @param {object} [pdf] - The resolved `pdf:` block.
+ * @param {{rootDir?: string, paths?: {content?: string}}} [config] - The
+ *   resolved configuration; the installed faces are searched when a note sets
+ *   text in one.
  * @returns {string[]} The arguments, in order.
  */
-export function typstFontArgs(pdf = {}) {
+export function typstFontArgs(pdf = {}, config) {
     // 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.
+    // directory and the installed script fonts extend the set rather than
+    // standing in for it.
     const fontPaths = [BOOK_FONTS_PATH];
     if (pdf.fonts?.path) fontPaths.push(pdf.fonts.path);
+    const scriptFonts = config && typstScriptFontPath(config);
+    if (scriptFonts) fontPaths.push(scriptFonts);
     return ["--ignore-system-fonts", "--font-path", fontPaths.join(path.delimiter)];
 }
 
@@ -2044,12 +2060,14 @@ export function typstWarnings(output) {
  * @param {string} typPath - The `.typ` file.
  * @param {string} pdfPath - Where the PDF goes.
  * @param {object} pdf - The resolved `pdf:` block.
+ * @param {{rootDir?: string, paths?: {content?: string}}} [config] - The
+ *   resolved configuration, for the installed faces.
  * @returns {{ok: boolean, message: string, findings: object[]}} What happened,
  *   and what the compiler warned about on the way.
  */
-export function compileTypst(typPath, pdfPath, pdf = {}) {
+export function compileTypst(typPath, pdfPath, pdf = {}, config) {
     const binary = pdf.binary || "typst";
-    const args = typstArgs(typPath, pdfPath, pdf);
+    const args = typstArgs(typPath, pdfPath, pdf, config);
     let result;
     try {
         result = spawnSync(binary, args, { encoding: "utf8" });

package/engine/pdf-render.mjs

@@ -91,6 +91,7 @@ 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 { 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 { inlineVerse, poetryStanzas, scanPoetry } from "./content-poetry.mjs";
@@ -370,7 +371,11 @@ function reportUnrenderable(source, definitions, opts, original) {
                 );
         }
     }
-    for (const error of [...scanSpans(source).errors, ...markupAnchorFindings(source)])
+    for (const error of [
+        ...scanSpans(source).errors,
+        ...scanRuns(source, opts.runs).errors,
+        ...markupAnchorFindings(source),
+    ])
         report(linePosition(error.line, error.column, opts), "error", error.message);
     for (const error of scanFigures(source).errors)
         report(linePosition(error.line, error.column, opts), "error", error.message);
@@ -462,6 +467,9 @@ function reportUnrenderable(source, definitions, opts, original) {
  *   Typst and is told nothing.
  * @param {string} [opts.file] - The file the markdown came from, named in every
  *   finding.
+ * @param {import("./content-scripts.mjs").RunContext} [opts.runs] - The
+ *   package's languages, faces and maps, which text marked with `lang=`,
+ *   `font=` and `map=` is checked against and set by.
  * @param {number} [opts.bodyLine] - The 1-based file line the body starts on, so
  *   a finding's line is the file's rather than the body's.
  * @param {number} [opts.bodyColumn] - The 1-based column the body starts at.
@@ -497,7 +505,7 @@ export function markdownToTypst(markdown, opts = {}) {
     } = opts;
     const given = opts.nested ? String(markdown ?? "") : stripHtmlComments(markdown);
     const separated = opts.footnoteDefinitions === undefined ? separateFootnotes(given) : null;
-    const source = separated?.markdown ?? given;
+    const authored = separated?.markdown ?? given;
     const definitions = opts.footnoteDefinitions ?? separated?.definitions ?? "";
     const footnoteState = opts.footnoteState ?? { seen: new Set() };
     const sharedOptions = {
@@ -508,7 +516,13 @@ export function markdownToTypst(markdown, opts = {}) {
     };
     // Read once, over the body as it arrived: every position a finding carries
     // is an offset into *this* string, and the renderer below walks slices of it.
-    if (!opts.nested) reportUnrenderable(source, definitions, opts, given);
+    if (!opts.nested) reportUnrenderable(authored, definitions, opts, given);
+    // Text marked with a language, a font or a map is rewritten once, ahead of
+    // every other pass, line for line; the nested calls below read the result.
+    const source =
+        opts.nested ? authored : (
+            renderRuns(authored, opts.runs, undefined, { target: "book" }).markdown
+        );
     // One map for the whole body, not one per block: a heading inside a
     // blockquote or a list item shares the entry's anchor namespace with every
     // other heading in the same body, because `sectionLabel` scopes by entry
@@ -584,7 +598,9 @@ export function markdownToTypst(markdown, opts = {}) {
                         insideAdmonition: false,
                     });
                     const anchor = block.id ? ` <${sectionLabel(anchorPrefix, block.id)}>` : "";
-                    output.push(`\n#block(width: 100%)[${content}]${anchor}\n`);
+                    output.push(
+                        `\n#block(width: 100%)[${scriptWrapped(content, block.classes, block.attributes)}]${anchor}\n`,
+                    );
                     cursor = block.end + 1;
                     continue;
                 }
@@ -771,7 +787,9 @@ function renderBlock(tokens, i, out, ctx) {
                     `${token.markup}${token.info}\n${token.content}${token.markup}`,
                 ).blocks[0];
                 const anchor = poem?.id ? ` <${sectionLabel(ctx.anchorPrefix, poem.id)}>` : "";
-                out.push(`\n#block(width: 100%)[${content}]${anchor}\n`);
+                out.push(
+                    `\n#block(width: 100%)[${scriptWrapped(content, poem?.classes, poem?.attributes)}]${anchor}\n`,
+                );
             } else out.push(rawBlock(token.content, token.info?.trim() || ""));
             return 1;
         }
@@ -1215,6 +1233,43 @@ function rawBlock(content, info) {
     return `\n${ticks}${lang}\n${text}\n${ticks}\n\n`;
 }
 
+/**
+ * The language code Typst's `text(lang:)` takes for a BCP 47 tag.
+ *
+ * Typst takes an ISO 639 code and applies the hyphenation of that language, so
+ * a real language passes its primary subtag and an invented one (`art-x-…`),
+ * which has no patterns, leaves the book's language alone.
+ *
+ * @param {string|null|undefined} tag - A BCP 47 tag.
+ * @returns {string|undefined} The code, or `undefined` for none.
+ */
+function typstLanguage(tag) {
+    const primary = /^([a-z]{2,3})(?:-|$)/i.exec(tag ?? "")?.[1]?.toLowerCase();
+    return primary && primary !== "art" ? primary : undefined;
+}
+
+/** The classes that set a run in a font: a face's run carries `script`. */
+const FONT_CLASSES = Object.freeze(["script", ...Object.values(GENERIC_FONTS)]);
+
+/**
+ * Wrap a block's Typst in its font, its language and its direction.
+ *
+ * @param {string} content - The block's Typst.
+ * @param {string[]|undefined} classes - The classes the block carries.
+ * @param {Record<string, string>|undefined} attributes - Its `lang` and `dir`.
+ * @returns {string} The content, unchanged when the block is marked with none.
+ */
+function scriptWrapped(content, classes = [], attributes = {}) {
+    const lang = typstLanguage(attributes.lang);
+    const direction = attributes.dir === "rtl" ? "#set text(dir: rtl)\n" : "";
+    if (!classes.some((name) => FONT_CLASSES.includes(name)) && !lang && !direction) return content;
+    const list = classes.map((name) => `"${escapeTypstString(name)}"`);
+    const arguments_ =
+        `classes: (${list.join(", ")}${list.length === 1 ? "," : ""})` +
+        (lang ? `, lang: "${lang}"` : "");
+    return `${direction}#book-script-text(${arguments_})[${content}]`;
+}
+
 /**
  * Render an inline token's children.
  *
@@ -1248,9 +1303,15 @@ function renderInline(token, ctx) {
                 const values = classes
                     .map((value) => '"' + escapeTypstString(value) + '"')
                     .join(", ");
+                const lang = typstLanguage(child.attrGet?.("lang"));
                 out.push(
-                    classes.length ?
-                        "#book-span(classes: (" + values + (classes.length === 1 ? "," : "") + "))["
+                    classes.length || lang ?
+                        "#book-span(classes: (" +
+                            values +
+                            (classes.length === 1 ? "," : "") +
+                            ")" +
+                            (lang ? `, lang: "${lang}"` : "") +
+                            ")["
                     :   "#box[",
                 );
                 break;
@@ -1632,6 +1693,30 @@ function renderIcon(token, ctx) {
  */
 const WIDE_TABLE_COLUMNS = 3;
 
+/**
+ * The `book-script-fonts` dictionary: each installed face's class, and each
+ * generic family's, to its font family and OpenType features.
+ *
+ * @param {import("./content-scripts.mjs").RunContext} runs - The installed faces.
+ * @param {{serif?: string, sans?: string, mono?: string}} families - The book's
+ *   own serif, sans and mono, which `font=serif`, `sans` and `mono` set.
+ * @returns {string} Typst markup.
+ */
+function scriptFontsTypst(runs, families) {
+    const entry = (name, family, features = []) =>
+        `"${escapeTypstString(name)}": (family: "${escapeTypstString(family)}", ` +
+        `features: (${features.map((feature) => `"${escapeTypstString(feature)}"`).join(", ")}` +
+        `${features.length === 1 ? "," : ""}))`;
+    const faces = [];
+    for (const face of runs.faces?.values() ?? [])
+        if (face.class && face.family) faces.push(entry(face.class, face.family, face.features));
+    for (const [generic, name] of Object.entries(GENERIC_FONTS)) {
+        const family = families[/** @type {"serif"|"sans"|"mono"} */ (generic)];
+        if (family) faces.push(entry(name, family));
+    }
+    return `#let book-script-fonts = (${faces.length ? faces.join(", ") : ":"})`;
+}
+
 /**
  * The Typst definitions the book's page furniture is drawn with.
  *
@@ -1669,20 +1754,37 @@ const WIDE_TABLE_COLUMNS = 3;
  * carries are not the same set, and a missing glyph on 2,000 feet is a
  * tofu box on every page of the book.
  *
+ * @param {import("./content-scripts.mjs").RunContext} [runs] - The installed
+ *   faces, each of whose classes sets its family.
+ * @param {{serif?: string, sans?: string, mono?: string}} [families] - The
+ *   book's own serif, sans and mono, which `font=serif`, `sans` and `mono` set.
  * @returns {string} Typst markup.
  */
-export function bookTypstPreamble() {
+export function bookTypstPreamble(runs = {}, families = {}) {
     return [
         "#let book-margin = 1.9cm",
         "#let book-page-width = 8.5in",
         "#let book-page-height = 11in",
         "#let book-text-width = book-page-width - 2 * book-margin",
         "#let book-text-height = book-page-height - 2 * book-margin",
+        // Each face's class, and each generic family's, sets its font family
+        // and OpenType features.
+        scriptFontsTypst(runs, families),
+        "#let book-script-text(body, classes: (), lang: none) = {\n" +
+            "  let styled = body\n" +
+            "  for name in classes {\n" +
+            "    if name in book-script-fonts {\n" +
+            "      let face = book-script-fonts.at(name)\n" +
+            "      styled = text(font: face.family, features: face.features, styled)\n" +
+            "    }\n" +
+            "  }\n" +
+            "  if lang != none { text(lang: lang, styled) } else { styled }\n" +
+            "}",
         // Span classes reach the book intact; name styling sets an absolute
         // weight so it remains bold inside an ordinary strong phrase.
-        "#let book-span(body, classes: ()) = {\n" +
+        "#let book-span(body, classes: (), lang: none) = {\n" +
             '  let styled = if classes.contains("name") { text(weight: "bold", body) } else { body }\n' +
-            "  box(styled)\n" +
+            "  box(book-script-text(styled, classes: classes, lang: lang))\n" +
             "}",
         // Use the file's natural measure for auto. Every requested width is
         // bounded by the available measure and by the height of a page.
@@ -2001,6 +2103,8 @@ function authorLine({ name, role }) {
  * @param {object} [opts.index] - As {@link module:engine/pdf-index.indexTerms}:
  *   `owns` limits the index to the notes this book is home to, and `foreign`
  *   (present only under `pdf.indexSeeAlso`) lists notes another book prints.
+ * @param {import("./content-scripts.mjs").RunContext} [opts.runs] - The
+ *   installed faces, which the preamble maps to font families.
  * @returns {string} A complete `.typ` document.
  */
 export function renderBook({
@@ -2019,6 +2123,7 @@ export function renderBook({
     copyright = "",
     license = "",
     index = {},
+    runs = {},
 } = {}) {
     // 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
@@ -2030,7 +2135,7 @@ export function renderBook({
     const mono = fonts.mono || "DejaVu Sans Mono";
     const out = [];
 
-    out.push(bookTypstPreamble());
+    out.push(bookTypstPreamble(runs, { serif, sans, mono }));
     out.push(indexPreamble({ seeAlso: index.foreign !== undefined }));
     out.push("");
     out.push(`#set document(title: "${escapeTypstString(title)}")`);

package/engine/run-rows.mjs

@@ -0,0 +1,119 @@
+/*
+ * 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
+ */
+
+/**
+ * Spans, divs and poetry fences marked with `lang=`, `font=` or `map=`, projected
+ * from own-note index records into the SQL `runs` relation. Every value is a
+ * column value and none is a key, so two notes writing one tag in different
+ * case are two rows. Documentation records and assets contribute no rows.
+ *
+ * @module
+ */
+
+import { canonicalKey, readCanonicalKey } from "./address.mjs";
+import { encodeAddresses } from "./address-values.mjs";
+import { isNoteRecord } from "./index-records.mjs";
+import { scanRuns } from "./content-scripts.mjs";
+
+/** Every column of the `runs` relation, in order. */
+export const RUN_COLUMNS = Object.freeze([
+    "owner",
+    "kind",
+    "lang",
+    "tag",
+    "font",
+    "map",
+    "line",
+    "column",
+]);
+
+/**
+ * One run as an index record carries it.
+ *
+ * @typedef {object} RecordRun
+ * @property {"span"|"block"|"poetry"} kind - The construct.
+ * @property {string|null} lang - The language it is set in, as written: its
+ *   own `lang=`, else the one the div or fence around it states.
+ * @property {string|null} tag - The BCP 47 tag it resolves to, or null.
+ * @property {string|null} font - Its font, as written and inherited the same way.
+ * @property {string|null} map - Its map, as written and inherited the same way.
+ * @property {number} line - 1-based file line of its opening.
+ * @property {number} column - 1-based UTF-16 file column of its opening.
+ */
+
+/**
+ * @typedef {RecordRun & {owner: string|null}} RunRow
+ */
+
+/**
+ * A note body's runs, at file positions, as an index record carries them.
+ *
+ * @param {string} body - The note's body.
+ * @param {object} options - Options.
+ * @param {import("./content-scripts.mjs").RunContext} [options.context] - The
+ *   configured languages, which give a declared name its tag.
+ * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
+ * @param {number} [options.bodyColumn] - The 1-based column of its first character.
+ * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] -
+ *   Session scanner projections.
+ * @returns {RecordRun[]} One entry per run, in source order.
+ */
+export function recordRuns(body, { context, bodyLine = 1, bodyColumn = 1, syntax } = {}) {
+    return scanRuns(body, context, syntax).runs.map((run) => ({
+        kind: run.kind,
+        lang: run.lang ?? null,
+        tag: run.tag ?? null,
+        font: run.font ?? null,
+        map: run.map ?? null,
+        line: bodyLine + run.line - 1,
+        column: run.column + (run.line === 1 ? bodyColumn - 1 : 0),
+    }));
+}
+
+/**
+ * The containing page's NOTE identity.
+ *
+ * @param {Record<string, any>} record - An own-note index record.
+ * @returns {string|null} The page Address, or null for an unaddressable record.
+ */
+export function ownerOf(record) {
+    const parts = readCanonicalKey(encodeAddresses(record.address?.canonical));
+    return parts ? canonicalKey(parts.package, "note", parts.type, parts.shortcode) : null;
+}
+
+/**
+ * Project recorded runs without reading sources or changing records.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, already
+ *   narrowed to the audience.
+ * @returns {RunRow[]} One row per run, in record then source order.
+ */
+export function runsRows(records) {
+    const rows = [];
+    for (const record of records) {
+        if (!record || !isNoteRecord(record) || !Array.isArray(record.runs)) continue;
+        const owner = ownerOf(record);
+        for (const run of record.runs)
+            rows.push({
+                owner,
+                kind: run.kind,
+                lang: run.lang ?? null,
+                tag: run.tag ?? null,
+                font: run.font ?? null,
+                map: run.map ?? null,
+                line: run.line,
+                column: run.column,
+            });
+    }
+    return rows;
+}