@heroiclands/package-build 23.12.6 → 23.12.7

package/engine/verb-pattern.mjs

@@ -0,0 +1,99 @@
+/*
+ * 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 language's one regular verb pattern, read once for every reader.** A
+ * language's `data.grammar.verbs` is `{ invariant: true }` or six `persons`
+ * endings, optionally with `replaces`. A present form is the citation form
+ * with the ending added; where the pattern states `replaces`, a citation form
+ * closing on those letters has them swapped for the ending, and one closing
+ * otherwise takes the ending whole, as a suffix's `replaces` does.
+ *
+ * The dictionary's verb table and a mapped run's lexicon check both read the
+ * pattern through {@link verbPattern} and build forms with {@link verbForm}.
+ *
+ * @module
+ */
+
+import { VERB_PERSON_FIELDS } from "./language-terms.mjs";
+
+/** Whether a value is a plain map. */
+const isMap = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/**
+ * A stated verb pattern, as its readers use it.
+ *
+ * @typedef {object} VerbPattern
+ * @property {boolean} invariant - Whether verbs keep the citation form for
+ *   every person.
+ * @property {string|undefined} replaces - The letters each ending takes the
+ *   place of, where the pattern states them.
+ * @property {Array<{name: string, label: string, ending: string}>} endings -
+ *   The six endings in presentation order; empty for an invariant pattern.
+ */
+
+/**
+ * Read a language's verb pattern.
+ *
+ * @param {unknown} verbs - The language's `data.grammar.verbs`, as authored or
+ *   as a SQL row carries it (absent fields `null`).
+ * @returns {VerbPattern|undefined} The pattern, or `undefined` where none is
+ *   stated in full.
+ */
+export function verbPattern(verbs) {
+    if (!isMap(verbs)) return undefined;
+    const replaces =
+        typeof verbs.replaces === "string" && verbs.replaces.trim() ? verbs.replaces : undefined;
+    if (verbs.invariant === true) return { invariant: true, replaces, endings: [] };
+    const persons = isMap(verbs.persons) ? verbs.persons : undefined;
+    if (!persons || !VERB_PERSON_FIELDS.every(({ name }) => typeof persons[name] === "string"))
+        return undefined;
+    return {
+        invariant: false,
+        replaces,
+        endings: VERB_PERSON_FIELDS.map(({ name, label }) => ({
+            name,
+            label,
+            ending: persons[name],
+        })),
+    };
+}
+
+/**
+ * A stem with its closing letters swapped for an ending, or with the ending
+ * added where the stem does not close on them.
+ *
+ * @param {string} stem - The stem.
+ * @param {string} ending - The ending.
+ * @param {string|undefined} letters - The closing letters the ending takes
+ *   the place of; none adds the ending.
+ * @returns {string} The form.
+ */
+export function replaceClosing(stem, ending, letters) {
+    return letters && stem.endsWith(letters) ?
+            stem.slice(0, -letters.length) + ending
+        :   stem + ending;
+}
+
+/**
+ * The present form of a verb for one ending.
+ *
+ * @param {string} citation - The citation form.
+ * @param {string} ending - The person's ending; empty leaves the citation
+ *   form, less any closing `replaces`.
+ * @param {string} [replaces] - The pattern's `replaces`.
+ * @returns {string} The form.
+ */
+export function verbForm(citation, ending, replaces) {
+    return replaceClosing(citation, ending, replaces);
+}

package/engine/word-pattern.mjs

@@ -0,0 +1,27 @@
+/*
+ * 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 a word is in running text.** A word is a maximal run of letters,
+ * combining marks and digits, and an apostrophe (`'` or `’`), a hyphen or an
+ * en dash joins two such runs into one word: `k'aralzon`, `Arzen-Thalor`.
+ * Anything else, whitespace and punctuation included, sits between words.
+ *
+ * The name catalog reads a label's last word by it, and a mapped run reads
+ * each word it looks up in a lexicon by it.
+ *
+ * @module
+ */
+
+/** One word; global, so `matchAll` walks every word of a text. */
+export const WORD = /[\p{L}\p{M}\p{N}]+(?:[’'–-][\p{L}\p{M}\p{N}]+)*/gu;

package/engine/word-rows.mjs

@@ -47,6 +47,12 @@ import {
     glossText,
 } from "./word-terms.mjs";
 
+/**
+ * The word's own keys a word row carries: all but `native`, whose entries are
+ * rows of the `natives` relation.
+ */
+const WORD_ROW_KEYS = Object.freeze(WORD_KEYS.filter((key) => key !== "native"));
+
 /** The columns a word row carries before the word's own keys. */
 const WORD_IDENTITY_COLUMNS = Object.freeze(["language", "position"]);
 
@@ -56,7 +62,7 @@ const WORD_DERIVED_COLUMNS = Object.freeze(["built_text", "built_parts", "senses
 /** Every column of the `words` relation, in order. */
 export const WORD_COLUMNS = Object.freeze([
     ...WORD_IDENTITY_COLUMNS,
-    ...WORD_KEYS,
+    ...WORD_ROW_KEYS,
     ...WORD_DERIVED_COLUMNS,
 ]);
 
@@ -260,7 +266,7 @@ export function wordRows(records, all = records) {
         words.forEach((entry, position) => {
             if (!isMap(entry)) return;
             const row = { language, position };
-            for (const key of WORD_KEYS) row[key] = entry[key] ?? null;
+            for (const key of WORD_ROW_KEYS) row[key] = entry[key] ?? null;
             if (row.name_sort === null) row.name_sort = row.form;
             const built = Array.isArray(entry.built) ? entry.built.map(String) : [];
             row.built_text = built.length ? built.join(" + ") : null;

package/engine/word-terms.mjs

@@ -99,6 +99,37 @@ export const WORD_SOURCE_FIELDS = Object.freeze([
     }),
 ]);
 
+/**
+ * The keys of one entry of a word's `native`.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const WORD_NATIVE_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "map",
+        kind: "string",
+        required: true,
+        shape: "a mapping note's `data.map.name`",
+        describe: "The map the native form is written for.",
+    }),
+    Object.freeze({
+        name: "font",
+        kind: "string",
+        shape: "a face the map lists",
+        describe:
+            "The one face the native form is for; unstated, it is for every face the map lists, " +
+            "and a form stated for a face wins over it there.",
+    }),
+    Object.freeze({
+        name: "text",
+        kind: "string",
+        required: true,
+        shape: "the word in the script, as the map's characters",
+        describe:
+            "The word as the script writes it, where the map's rows would write it otherwise.",
+    }),
+]);
+
 /**
  * The keys one word of a language note's `data.words` carries.
  *
@@ -209,6 +240,19 @@ export const WORD_FIELDS = Object.freeze([
         shape: "a frame of the language's `sounds.frames`",
         describe: "The frame a root is set in, named in the language's `sounds.frames`.",
     }),
+    Object.freeze({
+        name: "native",
+        kind: "list",
+        shape: "a list of `{ map, font?, text }`",
+        entries: Object.freeze({
+            kind: "map",
+            shape: "a map — `{ map, font?, text }`",
+            fields: WORD_NATIVE_FIELDS,
+        }),
+        describe:
+            "The word's native form under a map, stated only where the map's rows spell it " +
+            "differently. Its derived forms are spelled by the rows.",
+    }),
 ]);
 
 /** The keys of {@link WORD_FIELDS}, in declared order. */

package/hugo-theme/layouts/_default/baseof.html

@@ -9,6 +9,9 @@
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Cinzel:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&family=Lora:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="{{ "css/style.css" | relURL }}">
+  {{/* Script fonts: the site build sets params.scriptFonts only when it has
+       copied them. */}}
+  {{ with .Site.Params.scriptFonts }}<link rel="stylesheet" href="{{ . | relURL }}">{{ end }}
   {{/* Icon glyphs. SoHL documentation writes icons as <i class="fa-solid …">
        or <i class="ginf-…">, the same markup the Foundry client renders, so a
        page reads identically in a journal and here. Font Awesome's FREE set is

package/hugo-theme/static/css/style.css

@@ -3022,3 +3022,13 @@ summary.info-sidebar-title::after {
 .single-body .dictionary > div > dd > :is(p, ul, ol, dl, blockquote, pre, table, div) { text-indent:0; }
 .single-body .dictionary > div > dd > p:first-child { display:inline; }
 @media (max-width:600px) { .single-body .dictionary { --indent:100px; } }
+
+/* ---- Text in one of the faces ----
+   The font family and features come from the face's own class. A
+   right-to-left block or verse reads from the right. `font=serif`, `sans`
+   and `mono` set the site's own serif and mono, and the reader's sans. */
+.script-block { margin:1rem 0; line-height:1.7; }
+.script-block[dir="rtl"], .poetry[dir="rtl"] { text-align:start; }
+.font-serif { font-family:var(--font-body); }
+.font-sans { font-family:sans-serif; }
+.font-mono { font-family:var(--font-mono); }

package/manifest.mjs

@@ -54,6 +54,7 @@ import fsSync from "node:fs";
 import path from "node:path";
 
 import { withBaseStyle } from "./engine/base-styles.mjs";
+import { scriptFontFiles, withScriptFontStyle } from "./engine/script-font-delivery.mjs";
 import { emitDiagnostic, formatDiagnostic, positionOfYamlPath } from "./engine/diagnostics.mjs";
 import { metadataFileName } from "./engine/metadata-index.mjs";
 
@@ -571,11 +572,18 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     // the five that do have no stylesheet of their own to name it from. See
     // `engine/base-styles.mjs` for the layer it loads into and why that is what
     // lets a package override it.
-    const styles = withBaseStyle({
+    const withBase = withBaseStyle({
         declared: declared.styles,
         artifact: /** @type {"system"|"module"} */ (artifact),
         enabled: config.packageBuild?.baseStyles !== false,
     });
+    // The installed script fonts' stylesheet follows it, when the module
+    // carries them: see `engine/script-font-delivery.mjs`.
+    const styles = withScriptFontStyle({
+        styles: withBase,
+        artifact: /** @type {"system"|"module"} */ (artifact),
+        delivered: scriptFontFiles(config, ["woff2"]) !== undefined,
+    });
     if (styles !== undefined) merged.styles = styles;
 
     // The index every consumer resolves this package's addresses through.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.12.6",
+    "version": "23.12.7",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/content-config.d.mts

@@ -703,6 +703,12 @@ export type ContentBuildConfigInput = {
      * vocabulary is their union.
      */
     itemBuilders?: Record<string, ItemBuilderEntry> | readonly ItemRegistrySpec[] | undefined;
+    /**
+     * The languages a
+     * note may tag text with, by short
+     * name. Default `{}`.
+     */
+    languages?: Record<string, LanguageSpec> | undefined;
     /**
      * Packs to compile. More than one entry
      * may share a `type`: a note then names
@@ -891,6 +897,10 @@ export type ContentBuildConfig = {
      * none.
      */
     icons: import("./engine/content-icons.mjs").IconRegistry;
+    /**
+     *                                     Frozen; `{}` when absent.
+     */
+    languages: Readonly<Record<string, Readonly<LanguageSpec>>>;
     packs: readonly Readonly<ResolvedPackSpec>[];
     /**
      * Derived: every pack directory
@@ -918,3 +928,19 @@ export type ContentBuildConfig = {
     relationships: Readonly<Relationships>;
     publish: Readonly<PublishSwitches>;
 };
+/**
+ * One entry of `languages`.
+ */
+export type LanguageSpec = {
+    /**
+     * Its BCP 47 tag. A constructed language takes
+     * `art-x-<name>`.
+     */
+    tag: string;
+    /**
+     * The Address of its language note, whose
+     * `data.words` is the lexicon a mapped run in the
+     * language reads first.
+     */
+    note?: string | undefined;
+};

package/types/engine/compile-corpus.d.mts

@@ -16,7 +16,7 @@
  *   the index refuses is a note the compile must still *report*, exactly as the
  *   compile loop reported it when the loop was the first to see it.
  * @param {import("./content-session.mjs").ContentSession} [opts.session] - Captured context shared with other operations.
- * @returns {Promise<{currentDate: string, records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[], syntax?: import("./content-session.mjs").ContentSyntax}>} The corpus,
+ * @returns {Promise<{currentDate: string, runs: import("./content-scripts.mjs").RunContext, records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[], syntax?: import("./content-session.mjs").ContentSyntax}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
 export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, router, config, problems, session, }: {
@@ -29,6 +29,7 @@ export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, r
     session?: import("./content-session.mjs").ContentSession | undefined;
 }): Promise<{
     currentDate: string;
+    runs: import("./content-scripts.mjs").RunContext;
     records: object[];
     parsed: Map<string, object>;
     linkIndex: object;

package/types/engine/content-index.d.mts

@@ -81,6 +81,8 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   `name` reads `Map 1` rather than `Figure 1` where it is due — see
  *   {@link module:engine/content-figures.scanFigures}.
  * @param {import("./content-session.mjs").ContentSyntax} [options.syntax] - Session scanner projections.
+ * @param {import("./content-scripts.mjs").RunContext} [options.runContext] -
+ *   The configured languages, which give each run's `lang=` its tag.
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
@@ -92,7 +94,7 @@ export function asciiAliases(aliases: unknown): Array<string>;
  *   otherwise be overwritten without a word. `file` and, where the file was
  *   read, `position` ride on the error.
  */
-export function buildIndexRecord({ frontmatter, relPath, absPath, raw, contentPackage, body, bodyLine, bodyColumn, nameTypes, manifest, addressContext, dateContext, resolveRole, syntax, }: {
+export function buildIndexRecord({ frontmatter, relPath, absPath, raw, contentPackage, body, bodyLine, bodyColumn, nameTypes, manifest, addressContext, dateContext, resolveRole, syntax, runContext, }: {
     frontmatter: Record<string, any>;
     relPath: string;
     absPath?: string | undefined;
@@ -107,12 +109,13 @@ export function buildIndexRecord({ frontmatter, relPath, absPath, raw, contentPa
     dateContext?: object | undefined;
     resolveRole?: ((address: string) => string | undefined) | undefined;
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
+    runContext?: import("./content-scripts.mjs").RunContext | undefined;
 }): Record<string, any>;
 /**
  * Derive every index record belonging to one parsed note.
  * @param {Parameters<typeof buildIndexRecord>[0]} options - Authored note and its context.
  */
-export function indexRecordsForNote({ frontmatter, body, bodyLine, bodyColumn, nameTypes, relPath, absPath, raw, contentPackage, manifest, addressContext, dateContext, resolveRole, syntax, }: Parameters<typeof buildIndexRecord>[0]): object[];
+export function indexRecordsForNote({ frontmatter, body, bodyLine, bodyColumn, nameTypes, relPath, absPath, raw, contentPackage, manifest, addressContext, dateContext, resolveRole, syntax, runContext, }: Parameters<typeof buildIndexRecord>[0]): object[];
 /**
  * Write each note's resolved culture into its record, as `data.culture`.
  *
@@ -209,6 +212,8 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  *   calendar note's shortcode; see {@link module:engine/note-calendars}.
  * @param {string} [options.configFile] - The configuration file, where an
  *   unknown `defaultCalendar` is reported.
+ * @param {Readonly<Record<string, {tag: string}>>} [options.languages] - The
+ *   configured languages, which give each run's `lang=` its tag.
  * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
  *   Another package's entry for a canonical address, read for a parent that
  *   package publishes; see {@link resolveCultures}.
@@ -221,7 +226,7 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
+export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, languages, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
@@ -231,6 +236,9 @@ export function collectContentIndex(contentBase: string, { contentPackage, curre
     currentDate?: string | undefined;
     defaultCalendar?: string | undefined;
     configFile?: string | undefined;
+    languages?: Readonly<Record<string, {
+        tag: string;
+    }>> | undefined;
     foreignRecord?: ((key: string) => ({
         culture?: unknown;
     } | undefined)) | undefined;

package/types/engine/content-poetry.d.mts

@@ -49,3 +49,10 @@ export function renderPoetry(source: string): {
         message: string;
     }[];
 };
+/**
+ * The keys a poetry fence's attribute block takes. `lang`, `font` and `map`
+ * are read by `scanRuns` in content-scripts.mjs; `dir`, and on the site
+ * `data-pagefind-ignore`, are written by its rewrite of a fence set in one of
+ * the faces, and reach the element as they are written.
+ */
+export const POETRY_KEYS: readonly string[];

package/types/engine/content-scripts.d.mts

@@ -0,0 +1,226 @@
+/**
+ * The context a resolved configuration gives, and the maps an index holds.
+ *
+ * @param {{languages?: object, rootDir?: string}|undefined} config - The
+ *   resolved configuration.
+ * @param {Iterable<Record<string, any>>} [records] - The content index's
+ *   records, whose mapping notes give the maps. Without them no map is known.
+ * @returns {RunContext} Its languages, the faces installed where it sits, and
+ *   the maps. A fonts package that cannot be read gives no faces; a run naming
+ *   one is reported.
+ */
+export function runContext(config: {
+    languages?: object;
+    rootDir?: string;
+} | undefined, records?: Iterable<Record<string, any>>): RunContext;
+/**
+ * Find the spans, divs and poetry fences marked with `lang=`, `font=` or
+ * `map=`, and every fault in their markup and their text.
+ *
+ * @param {string} source - Authored Markdown: a note body, or a whole file
+ *   whose frontmatter is blanked.
+ * @param {RunContext} [ctx] - The configured languages, the installed faces
+ *   and the maps. Without them every `lang=` must be a tag, every face and
+ *   map is unknown, and only `mono`, `serif` and `sans` are fonts.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Session
+ *   scanner projections, so the source's spans and blocks are scanned once.
+ * @returns {{runs: Run[], errors: Array<{line: number, column: number, message: string}>, warnings: Array<{line: number, column: number, message: string}>}}
+ *   The runs in source order, and each finding at its 1-based position. A
+ *   warning is a `lang=` read as a tag that sits within one edit of a
+ *   declared name.
+ */
+export function scanRuns(source: string, ctx?: RunContext, syntax?: import("./content-session.mjs").ContentSyntax): {
+    runs: Run[];
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+    warnings: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * Rewrite text marked with `lang=`, `font=` and `map=` into the plain span,
+ * div and poetry grammar the rest of each chain renders, one line for one line.
+ *
+ * - **The map, if any, is applied first.** Characters Markdown would read are
+ *   then backslash-escaped, so they reach every later pass as characters.
+ * - **The construct carries** the language's tag as `lang`, the face's class
+ *   (with `script`, and `script-block` on a div) or the generic family's
+ *   class. On the site, a face's construct also carries
+ *   `data-pagefind-ignore`, since site search cannot read its code points;
+ *   Foundry and the book receive no search marker.
+ * - **A div or fence in a right-to-left face** carries `dir=rtl`. No direction
+ *   mark, `<bdo>` or `<bdi>` is ever written: the code points carry their own
+ *   direction.
+ *
+ * A run with a finding is left as written; {@link scanRuns} reports it.
+ *
+ * @param {string} source - Authored Markdown: a note body.
+ * @param {RunContext} [ctx] - The configured languages, faces and maps.
+ * @param {import("./content-session.mjs").ContentSyntax} [syntax] - Session
+ *   scanner projections.
+ * @param {{target?: "site"|"foundry"|"book"}} [options] - The target the
+ *   Markdown is rendered for; only `site` writes the search marker.
+ * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
+ *   The rewritten Markdown, and the findings of {@link scanRuns}.
+ */
+export function renderRuns(source: string, ctx?: RunContext, syntax?: import("./content-session.mjs").ContentSyntax, options?: {
+    target?: "site" | "foundry" | "book";
+}): {
+    markdown: string;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/** The keys this module reads, which no construct passes through as written. */
+export const RUN_KEYS: readonly string[];
+/** The generic families `font=` may name, each with the class that sets it. */
+export const GENERIC_FONTS: Readonly<{
+    mono: "font-mono";
+    serif: "font-serif";
+    sans: "font-sans";
+}>;
+/**
+ * One marked construct, with what rendering it needs beside its {@link Run}.
+ */
+export type RunDetail = {
+    /**
+     * - The run.
+     */
+    run: Run;
+    /**
+     * -
+     * What the construct carries besides the run keys.
+     */
+    own: {
+        id: string;
+        classes: string[];
+        values: Array<[string, string]>;
+    };
+    /**
+     * - The run keys it states itself.
+     */
+    keys: Record<string, string>;
+    /**
+     * - Whether its text is set.
+     */
+    plain: boolean;
+    /**
+     * - Its face.
+     */
+    face: import("./script-fonts.mjs").Face | undefined;
+    /**
+     * - Its generic family's class.
+     */
+    generic: string | undefined;
+    /**
+     * - Its map.
+     */
+    textMap: import("./text-maps.mjs").TextMap | undefined;
+    /**
+     * - Its map,
+     * face and lexicon, which its text is set by.
+     */
+    mapping: import("./map-lexicon.mjs").Mapping | undefined;
+    /**
+     * - The marked spans inside it.
+     */
+    holes: Map<number, number>;
+    /**
+     * - A div's or fence's body, as
+     * offsets: the first body line's start to the end of the last.
+     */
+    body: [number, number] | undefined;
+    /**
+     * - A span's offset of its closing `]`.
+     */
+    contentEnd: number | undefined;
+};
+/**
+ * What a run is checked against.
+ */
+export type RunContext = {
+    /**
+     * - The
+     * configured languages.
+     */
+    languages?: Readonly<Record<string, {
+        tag: string;
+    }>> | undefined;
+    /**
+     * -
+     * The installed faces by slug, from
+     * {@link module :engine/script-fonts.resolveScriptFonts}.
+     */
+    faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face> | undefined;
+    /**
+     * -
+     * The mapping notes' maps by name, from
+     * {@link module :engine/text-maps.mapsFromRecords}.
+     */
+    maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap> | undefined;
+    /**
+     * -
+     * Each configured language's lexicon by name, from
+     * {@link module :engine/map-lexicon.lexiconsFromRecords}.
+     */
+    lexicons?: ReadonlyMap<string, import("./map-lexicon.mjs").Lexicon> | undefined;
+    /**
+     * -
+     * What each configured language's mapped runs are checked against, from
+     * {@link module :engine/run-words.wordBooksFromRecords}.
+     */
+    wordBooks?: ReadonlyMap<string, import("./run-words.mjs").WordBook> | undefined;
+};
+/**
+ * One span, div or poetry fence carrying `lang=`, `font=` or `map=`. Its
+ * `lang`, `font` and `map` are the ones it is set with: its own, else the
+ * innermost div or fence around it that states one.
+ */
+export type Run = {
+    /**
+     * - Which construct.
+     */
+    kind: "span" | "block" | "poetry";
+    /**
+     * - The language as written.
+     */
+    lang: string | undefined;
+    /**
+     * - The BCP 47 tag it resolves to; `undefined`
+     * when it resolves to none.
+     */
+    tag: string | undefined;
+    /**
+     * - The font as written.
+     */
+    font: string | undefined;
+    /**
+     * - The map as written.
+     */
+    map: string | undefined;
+    /**
+     * - 1-based line of the construct's opening.
+     */
+    line: number;
+    /**
+     * - 1-based UTF-16 column of its opening.
+     */
+    column: number;
+    /**
+     * - A span's offset of `[`; a div's or fence's
+     * 0-based opening line.
+     */
+    start: number;
+    /**
+     * - A span's offset past its attributes; a div's or
+     * fence's 0-based closing line.
+     */
+    end: number;
+};

package/types/engine/data-keys.d.mts

@@ -5,7 +5,7 @@
  * @property {string} name - The key as an author writes it.
  * @property {string} [kind] - Its value's shape: `string`, `date`, `number`,
  *   `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
- *   `string-or-list`, or `string-list-or-map` — see {@link fitsKind}. Absent, the check
+ *   `string-or-list`, `string-list-or-map` or `list-or-map` — see {@link fitsKind}. Absent, the check
  *   makes no claim about the value.
  * @property {readonly string[]} [allowed] - The closed set a present value is
  *   one of, where the key takes a fixed word.
@@ -97,7 +97,7 @@ export type InnerKeySpec = {
     /**
      * - Its value's shape: `string`, `date`, `number`,
      * `integer`, `boolean`, `address`, `list`, `map`, `scalar-or-map`,
-     * `string-or-list`, or `string-list-or-map` — see {@link fitsKind}. Absent, the check
+     * `string-or-list`, `string-list-or-map` or `list-or-map` — see {@link fitsKind}. Absent, the check
      * makes no claim about the value.
      */
     kind?: string | undefined;