@heroiclands/package-build 23.12.5 → 23.12.7

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/reckoning-markers.mjs

@@ -209,13 +209,69 @@ export function resolveReckoningMarkers(index, daysPerYear) {
     return { eras, markers, findings };
 }
 
+/**
+ * The key a note's resolved calendar is filed under: its type and shortcode.
+ *
+ * @param {object|undefined} fm - A note's frontmatter or record.
+ * @returns {string|undefined} The key.
+ */
+export function noteCalendarKey(fm) {
+    return fm?.type && fm?.shortcode ? `${fm.type}\u0000${fm.shortcode}` : undefined;
+}
+
+/**
+ * A record's `resolvedCalendar` as its canonical Address string: an Address
+ * tuple, as a record in memory carries it, or the string an encoded record
+ * carries.
+ *
+ * @param {unknown} value - The value.
+ * @returns {string|undefined} The Address, or `undefined` for none.
+ */
+export function calendarAddress(value) {
+    if (typeof value === "string") return value || undefined;
+    return value && typeof value === "object" && "shortcode" in value ?
+            renderAddress(/** @type {any} */ (value))
+        :   undefined;
+}
+
+/**
+ * Each note's resolved calendar, by {@link noteCalendarKey}, from the
+ * `resolvedCalendar` the content index writes on a record.
+ *
+ * @param {Iterable<object>|undefined} notes - Index records, or
+ *   `{ fm, resolvedCalendar }` entries.
+ * @returns {Map<string, string>} Note key to the calendar's canonical Address.
+ */
+export function noteCalendarMap(notes) {
+    const out = new Map();
+    for (const note of notes ?? []) {
+        const calendar = calendarAddress(note?.resolvedCalendar);
+        if (!calendar) continue;
+        const key = noteCalendarKey(note?.fm ?? note?.frontmatter ?? note);
+        if (key && !out.has(key)) out.set(key, calendar);
+    }
+    return out;
+}
+
 /** One resolved date context per corpus index. */
 const contexts = new WeakMap();
 
-/** Read the world's year length and resolve every calendar era in one corpus. */
+/**
+ * Read the world's year length and resolve every calendar era in one corpus.
+ *
+ * The context also carries `noteCalendars`, each note's resolved calendar by
+ * note, read from the `resolvedCalendar` the content index writes on a record;
+ * {@link module:engine/note-calendars.noteCalendar} reads it.
+ */
 export function reckoningContext(index) {
     if (!index || typeof index !== "object")
-        return { eras: new Map(), markers: new Map(), daysPerYear: undefined, findings: [] };
+        return {
+            eras: new Map(),
+            markers: new Map(),
+            daysPerYear: undefined,
+            findings: [],
+            noteCalendars: new Map(),
+        };
     const cached = contexts.get(index);
     if (cached) return cached;
     const world = (index.notes ?? []).find((note) => {
@@ -224,7 +280,11 @@ export function reckoningContext(index) {
     });
     const fm = world?.fm ?? world?.frontmatter ?? world;
     const daysPerYear = fm?.data?.year?.days;
-    const context = { ...resolveReckoningMarkers(index, daysPerYear), daysPerYear };
+    const context = {
+        ...resolveReckoningMarkers(index, daysPerYear),
+        daysPerYear,
+        noteCalendars: noteCalendarMap(index.notes),
+    };
     contexts.set(index, context);
     return context;
 }

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;
+}