@heroiclands/package-build 23.12.5 → 23.12.7

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;

package/types/engine/dictionary-rows.d.mts

@@ -1,3 +1,18 @@
+/**
+ * A noun's stated plural, or the first literal ending replacement that fits.
+ *
+ * @param {{form: string, class?: unknown, plural?: unknown}} word - A word of
+ *   `data.words`.
+ * @param {Record<string, any>|undefined} grammar - Its language's
+ *   `data.grammar`.
+ * @returns {string|null} The plural, or `null` for a word that is no noun or
+ *   that no rule fits.
+ */
+export function pluralOf(word: {
+    form: string;
+    class?: unknown;
+    plural?: unknown;
+}, grammar: Record<string, any> | undefined): string | null;
 /**
  * The stable prose anchor of a word in one language's dictionary. The exact
  * language and NFC form identify it, including case and accents.

package/types/engine/event-rows.d.mts

@@ -1,15 +1,30 @@
+/**
+ * Every calendar a set of records can print an event's date in: each calendar
+ * note's canonical Address, and every calendar a note resolves to.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records, every
+ *   Address a string.
+ * @returns {string[]} The calendars, sorted.
+ */
+export function eventCalendars(records: Iterable<Record<string, any>>): string[];
 /**
  * The `events` rows of a set of index records.
  *
  * @param {Iterable<Record<string, any>>} records - Index records, every
  *   Address a string, already narrowed to the audience being published to.
  * @param {object} [dates] - The reckoning context the dates are printed in.
+ * @param {readonly string[]} [calendars] - The calendars `whenIn` and
+ *   `untilIn` are keyed by: {@link eventCalendars} of every record of the
+ *   corpus, whatever the audience, so every surface's relation has the same
+ *   keys. Absent, those of `records`.
  * @returns {object[]} One row per event entry, in record then entry order.
  */
-export function eventRows(records: Iterable<Record<string, any>>, dates?: object): object[];
+export function eventRows(records: Iterable<Record<string, any>>, dates?: object, calendars?: readonly string[]): object[];
 /** The sort keys a row carries, after the event's own keys. */
 export const EVENT_SORT_COLUMNS: readonly string[];
 /** The printed dates a row carries, after the sort keys. */
 export const EVENT_TEXT_COLUMNS: readonly string[];
+/** The dates a row carries in every calendar, after the printed ones. */
+export const EVENT_CALENDAR_COLUMNS: readonly string[];
 /** Every column of the `events` relation, in order. */
 export const EVENT_COLUMNS: any;

package/types/engine/event-views.d.mts

@@ -34,7 +34,7 @@ export function eventViewSections(db: object, records: Iterable<object>, fileOf:
  *
  * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
  *   applies: (record: object) => boolean,
- *   query: (self: string[], shape: CorpusShape, columns?: {felt?: boolean}) => {fence: string, own?: string}|null,
+ *   query: (self: string[], shape: CorpusShape, columns?: {felt?: boolean, calendar?: string}) => {fence: string, own?: string}|null,
  *   owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>,
  *   felt?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>}>>}
  */
@@ -44,6 +44,7 @@ export const EVENT_VIEWS: ReadonlyArray<Readonly<{
     applies: (record: object) => boolean;
     query: (self: string[], shape: CorpusShape, columns?: {
         felt?: boolean;
+        calendar?: string;
     }) => {
         fence: string;
         own?: string;

package/types/engine/helpers.d.mts

@@ -10,12 +10,16 @@
  * @param {(address: string) => string|undefined} [resolveRole] - From a
  *   picture's address to the role its asset declares — see
  *   {@link module:engine/content-figures.scanFigures}.
+ * @param {import("./content-scripts.mjs").RunContext} [runs] - The package's
+ *   languages, faces and maps. Given, text marked with `lang=`, `font=` and
+ *   `map=` is rewritten first, so it is tagged for its language, mapped and
+ *   set in its font.
  * @returns {string} The rendered HTML.
  */
 export function renderFoundryMarkdown(body: string, figures?: Array<{
     id: string;
     label: string;
-}>, footnoteNumbers?: Map<string, number>, docId?: string, resolveRole?: (address: string) => string | undefined): string;
+}>, footnoteNumbers?: Map<string, number>, docId?: string, resolveRole?: (address: string) => string | undefined, runs?: import("./content-scripts.mjs").RunContext): string;
 /**
  * Parses a markdown file with LF or CRLF YAML frontmatter delimiters.
  *

package/types/engine/journals.d.mts

@@ -134,13 +134,15 @@ export function journalPageId(entryId: string, page: {
  *   carries its own figure already, from {@link splitPages}.
  * @param {(address: string) => string|undefined} [resolveRole] - See
  *   {@link splitPages}.
+ * @param {import("./content-scripts.mjs").RunContext} [runs] - The package's
+ *   languages, faces and maps — see {@link module:engine/helpers.renderFoundryMarkdown}.
  * @returns {Array<{_id: string, name: string, type: string,
  *   title: {show: boolean, level: number},
  *   text: {format: number, content: string}, _key: string,
  *   ownership?: {default: number}}>} The page documents, in order.
  * @throws {Error} When the note has no content at all, or repeats an anchor.
  */
-export function buildPages(rawPages: Array<object>, entryId: string, noteName: string, figures: Array<object>, resolveRole?: (address: string) => string | undefined): Array<{
+export function buildPages(rawPages: Array<object>, entryId: string, noteName: string, figures: Array<object>, resolveRole?: (address: string) => string | undefined, runs?: import("./content-scripts.mjs").RunContext): Array<{
     _id: string;
     name: string;
     type: string;
@@ -192,9 +194,11 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   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} [params.syntax] - Session scanner projections.
+ * @param {import("./content-scripts.mjs").RunContext} [params.runs] - The package's
+ *   languages, faces and maps — see {@link module:engine/helpers.renderFoundryMarkdown}.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, resolveRole, syntax, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, stats, infoboxes, notice, resolveRole, syntax, runs, }: {
     id: string;
     name: string;
     markdown: string;
@@ -209,6 +213,7 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, stats,
     notice?: string | undefined;
     resolveRole?: ((address: string) => string | undefined) | undefined;
     syntax?: import("./content-session.mjs").ContentSyntax | undefined;
+    runs?: import("./content-scripts.mjs").RunContext | undefined;
 }): object;
 /**
  * Journals pack compiler.

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

@@ -20,3 +20,5 @@ export function checkLanguageData(note: object, { index, types }?: {
     index?: object | undefined;
     types?: readonly string[] | undefined;
 }): object[];
+/** How a foreign row that its tongue's register does not bear out is reported. */
+export const FOREIGN_ROW_SEVERITY: "warning";

package/types/engine/language-tag.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Whether a value is a BCP 47 language tag.
+ *
+ * @param {unknown} value - The value to test.
+ * @returns {boolean} Whether it is a well-formed tag with no repeated variant
+ *   or extension singleton.
+ */
+export function isLanguageTag(value: unknown): boolean;

package/types/engine/language-terms.d.mts

@@ -321,7 +321,8 @@ export const NEAR_NAME_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[]
 export const NAMING_FIELDS: readonly import("./data-keys.mjs").InnerKeySpec[];
 /**
  * The six present persons of the one optional regular verb pattern, in
- * presentation order. Empty endings leave the citation form unchanged.
+ * presentation order. Each ending is added to the citation form, or takes the
+ * place of its closing `replaces`; an empty ending adds nothing.
  *
  * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
  */

package/types/engine/map-lexicon.d.mts

@@ -0,0 +1,274 @@
+/**
+ * Each configured language's lexicon, read from the language note its `note`
+ * names. A language with no `note`, or one naming no language note, has none.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string}} config -
+ *   The resolved configuration.
+ * @returns {Map<string, Lexicon>} The lexicons by language name.
+ */
+export function lexiconsFromRecords(records: Iterable<Record<string, any>> | undefined, config?: {
+    languages?: Readonly<Record<string, {
+        tag: string;
+        note?: string;
+    }>>;
+    contentPackage?: string;
+}): Map<string, Lexicon>;
+/**
+ * The language note each configured language's `note` names, by language
+ * name. A language with no `note`, or one naming no language note, is absent.
+ *
+ * @param {Iterable<Record<string, any>>|undefined} records - Index records.
+ * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string}} config -
+ *   The resolved configuration.
+ * @returns {Map<string, Record<string, any>>} The records.
+ */
+export function languageRecordsByName(records: Iterable<Record<string, any>> | undefined, { languages, contentPackage }?: {
+    languages?: Readonly<Record<string, {
+        tag: string;
+        note?: string;
+    }>>;
+    contentPackage?: string;
+}): Map<string, Record<string, any>>;
+/**
+ * Each `languages.<name>.note` that names no language note, at its key.
+ *
+ * @param {{languages?: Readonly<Record<string, {tag: string, note?: string}>>, contentPackage?: string, configFile?: string, configText?: string}} config -
+ *   The resolved configuration, and where it was read from.
+ * @param {Iterable<Record<string, any>>} records - Index records.
+ * @returns {object[]} The findings.
+ */
+export function languageNoteFindings(config: {
+    languages?: Readonly<Record<string, {
+        tag: string;
+        note?: string;
+    }>>;
+    contentPackage?: string;
+    configFile?: string;
+    configText?: string;
+}, records: Iterable<Record<string, any>>): object[];
+/**
+ * A lookup of a word's native form under one map in one face: the form stated
+ * for the face, else the one stated for no face.
+ *
+ * @param {Lexicon|undefined} lexicon - The lexicon.
+ * @param {string} map - The map's name.
+ * @param {string|undefined} font - The face.
+ * @returns {((word: string) => string|undefined)|undefined} The lookup, or
+ *   `undefined` with no lexicon.
+ */
+export function nativeLookup(lexicon: Lexicon | undefined, map: string, font: string | undefined): ((word: string) => string | undefined) | undefined;
+/**
+ * What a run, a passage or a listing is mapped by.
+ *
+ * @typedef {object} Mapping
+ * @property {import("./text-maps.mjs").TextMap} map - The map.
+ * @property {string|undefined} font - The face, whose own rows come first.
+ * @property {((word: string) => string|undefined)|undefined} native - The
+ *   language's native forms under the map in the face.
+ */
+/**
+ * The one path from a map, a face and a language to what rewrites the text.
+ *
+ * @param {{maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>, lexicons?: ReadonlyMap<string, Lexicon>}} ctx -
+ *   The run context.
+ * @param {{map: string, font?: string, lang?: string}} keys - The map, the face
+ *   and the language.
+ * @returns {Mapping|undefined} The mapping, or `undefined` for an unknown map.
+ */
+export function mappingFor(ctx: {
+    maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>;
+    lexicons?: ReadonlyMap<string, Lexicon>;
+}, { map, font, lang }: {
+    map: string;
+    font?: string;
+    lang?: string;
+}): Mapping | undefined;
+/**
+ * Why a face is not one a map is for, or `undefined` where it is.
+ *
+ * @param {import("./text-maps.mjs").TextMap} map - The map.
+ * @param {string} font - The face's slug.
+ * @returns {string|undefined} The problem.
+ */
+export function fontProblem(map: import("./text-maps.mjs").TextMap, font: string): string | undefined;
+/**
+ * What is wrong with a capitalised word whose native form the rows cannot
+ * capitalise.
+ *
+ * @param {string} word - The word as written.
+ * @param {string} lower - The lowercase form the lexicon states.
+ * @param {string|undefined} lang - The language.
+ * @param {string} map - The map's name.
+ * @returns {string} The message.
+ */
+export function uncapitalisedMessage(word: string, lower: string, lang: string | undefined, map: string): string;
+/**
+ * Map a passage exactly as the build maps a run with the same keys.
+ *
+ * @param {object} ctx - The run context.
+ * @param {{map: string, font?: string, lang?: string}} keys - The map, the face
+ *   and the language.
+ * @param {string} text - The passage, with no escapes.
+ * @returns {{text: string}|{problem: string, about: string}} The mapped text, or the problem.
+ */
+export function transliterate(ctx: object, keys: {
+    map: string;
+    font?: string;
+    lang?: string;
+}, text: string): {
+    text: string;
+} | {
+    problem: string;
+    about: string;
+};
+/**
+ * Every word of a language's lexicon with its native form under a map: the
+ * stated exception, else the rows' spelling, each exactly as the build gives
+ * it.
+ *
+ * @param {object} ctx - The run context.
+ * @param {{lang: string, map: string, font?: string}} keys - The language, the
+ *   map and the face.
+ * @returns {{entries: Array<{form: string, native: string, exception: boolean, class: string|null, gloss: string|null}>}|{problem: string, about: string}}
+ *   The words in `data.words` order, or the problem.
+ */
+export function lexiconEntries(ctx: object, { lang, map, font }: {
+    lang: string;
+    map: string;
+    font?: string;
+}): {
+    entries: Array<{
+        form: string;
+        native: string;
+        exception: boolean;
+        class: string | null;
+        gloss: string | null;
+    }>;
+} | {
+    problem: string;
+    about: string;
+};
+/**
+ * Check a mapping note's `fonts` against the installed faces: an unknown face
+ * and a face listed twice, at the entry, and each code point a listed face
+ * lacks, at the row that writes it.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>, maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>}} ctx -
+ *   The run context.
+ * @returns {object[]} The findings.
+ */
+export function checkMapFonts(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, ctx: {
+    faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>;
+    maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>;
+}): object[];
+/**
+ * Check a language note's native forms against the maps and faces: an unknown
+ * map, a face the map is not for, a second form for one map and face, a form
+ * that states what the rows already give, and a code point a face it applies
+ * in does not draw. The shape of each entry is the data-key check's.
+ *
+ * @param {{file: string, raw?: string, fm?: Record<string, any>}} note - The note.
+ * @param {{faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>, maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>}} ctx -
+ *   The run context.
+ * @returns {object[]} The findings.
+ */
+export function checkLexiconNatives(note: {
+    file: string;
+    raw?: string;
+    fm?: Record<string, any>;
+}, ctx: {
+    faces?: ReadonlyMap<string, import("./script-fonts.mjs").Face>;
+    maps?: ReadonlyMap<string, import("./text-maps.mjs").TextMap>;
+}): object[];
+/**
+ * One row per native form of a language note's word, for the `natives`
+ * relation: a text is a value of a row, never a struct key, so forms that
+ * differ only in case stay apart.
+ *
+ * @param {Iterable<Record<string, any>>} records - Index records.
+ * @returns {Array<Record<string, string|number|null>>} The rows; `word` is the
+ *   word's 0-based place in `data.words`, `native` the form's in its `native`.
+ */
+export function nativeRows(records: Iterable<Record<string, any>>): Array<Record<string, string | number | null>>;
+/** Every column of the `natives` relation, in order. */
+export const NATIVE_COLUMNS: readonly string[];
+/**
+ * One native form, read.
+ */
+export type NativeForm = {
+    /**
+     * - The map it is written for.
+     */
+    map: string;
+    /**
+     * - The one face it is for.
+     */
+    font: string | undefined;
+    /**
+     * - The word in the script.
+     */
+    text: string;
+};
+/**
+ * One word of a lexicon.
+ */
+export type LexiconWord = {
+    /**
+     * - The word as cited.
+     */
+    form: string;
+    /**
+     * - Its class.
+     */
+    class: string | null;
+    /**
+     * - Its senses, joined by `; `.
+     */
+    gloss: string | null;
+    /**
+     * - Its native forms.
+     */
+    natives: readonly NativeForm[];
+};
+/**
+ * A language's lexicon.
+ */
+export type Lexicon = {
+    /**
+     * - The language's configured name.
+     */
+    language: string;
+    /**
+     * - Its words, in `data.words` order.
+     */
+    words: readonly LexiconWord[];
+    /**
+     * - The native
+     * forms by the word's form, NFC; the first word of a form keeps it.
+     */
+    byForm: ReadonlyMap<string, readonly NativeForm[]>;
+};
+/**
+ * What a run, a passage or a listing is mapped by.
+ */
+export type Mapping = {
+    /**
+     * - The map.
+     */
+    map: import("./text-maps.mjs").TextMap;
+    /**
+     * - The face, whose own rows come first.
+     */
+    font: string | undefined;
+    /**
+     * - The
+     * language's native forms under the map in the face.
+     */
+    native: ((word: string) => string | undefined) | undefined;
+};

package/types/engine/markup-validation.d.mts

@@ -4,9 +4,14 @@
  * @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: string, file: string, syntax?: import("./content-session.mjs").ContentSyntax): Array<{
+export function markupFindings(source: string, file: string, syntax?: import("./content-session.mjs").ContentSyntax, runs?: import("./content-scripts.mjs").RunContext): Array<{
     file: string;
     line: number;
     column: number;

package/types/engine/note-calendars.d.mts

@@ -0,0 +1,60 @@
+/**
+ * Write each note's resolved calendar into its record, as `resolvedCalendar`.
+ *
+ * Reads each note's authored `data.calendar`, `data.culture` and
+ * `data.parents`, so it runs before the index writes a resolved culture over
+ * `data.culture`. A culture or parent in another package contributes the
+ * calendar its published entry states in `data.calendar`, and nothing else.
+ *
+ * @param {Array<Record<string, any>>} records - Index records, every Address a
+ *   tuple. Records that are not notes are passed over.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the records belong to.
+ * @param {string} [options.defaultCalendar] - The configured calendar of last
+ *   resort, a calendar note's shortcode.
+ * @param {string} [options.configFile] - The configuration file, where an
+ *   unknown `defaultCalendar` is reported.
+ * @param {string} [options.contentBase] - The content tree, for opening a note
+ *   to locate a finding.
+ * @param {(key: string) => Record<string, any>|undefined} [options.foreignRecord] -
+ *   Another package's entry for a canonical address.
+ * @param {object[]} [options.problems] - Receives each finding. Omitted, the
+ *   findings are collected and one Error lists them all.
+ * @param {Map<string, {raw: string}>} [options.parsed] - Notes already read, keyed by file.
+ * @returns {Array<Record<string, any>>} The same records.
+ * @throws {Error} When `problems` is omitted and anything is reported.
+ */
+export function resolveNoteCalendars(records: Array<Record<string, any>>, { contentPackage, defaultCalendar, configFile, contentBase, foreignRecord, problems, parsed }: {
+    contentPackage: string;
+    defaultCalendar?: string | undefined;
+    configFile?: string | undefined;
+    contentBase?: string | undefined;
+    foreignRecord?: ((key: string) => Record<string, any> | undefined) | undefined;
+    problems?: object[] | undefined;
+    parsed?: Map<string, {
+        raw: string;
+    }> | undefined;
+}): Array<Record<string, any>>;
+/**
+ * The configuration file in a package root, where a configured value is
+ * reported.
+ *
+ * @param {string|undefined} rootDir - The package root.
+ * @param {readonly string[]} names - The file names a configuration may take.
+ * @returns {string|undefined} The first that exists.
+ */
+export function configFileIn(rootDir: string | undefined, names: readonly string[]): string | undefined;
+/**
+ * The calendar a note's dates print in: the one the content index resolved for
+ * it, where the reckoning context carries it, else the note's own
+ * `data.calendar`.
+ *
+ * @param {object|undefined} fm - The note's frontmatter.
+ * @param {{noteCalendars?: Map<string, string>}} [dates] - The reckoning context.
+ * @returns {string|undefined} The calendar's Address or shortcode.
+ */
+export function noteCalendar(fm: object | undefined, dates?: {
+    noteCalendars?: Map<string, string>;
+}): string | undefined;
+/** The configuration key naming the calendar of last resort. */
+export const DEFAULT_CALENDAR_KEY: "defaultCalendar";

package/types/engine/pdf-build.d.mts

@@ -184,17 +184,33 @@ export function buildPdf({ config, configPath, book, out, version, compile, read
  * @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: string, pdfPath: string, pdf?: object): string[];
+export function typstArgs(typPath: string, pdfPath: string, pdf?: object, config?: {
+    rootDir?: string;
+    paths?: {
+        content?: string;
+    };
+}): string[];
 /**
  * The flags that decide which faces a layout uses, shared by the compile and by
  * 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?: object): string[];
+export function typstFontArgs(pdf?: object, config?: {
+    rootDir?: string;
+    paths?: {
+        content?: string;
+    };
+}): string[];
 /**
  * The compiler's own warnings, as findings.
  *
@@ -224,10 +240,17 @@ export function typstWarnings(output: string): Array<{
  * @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: string, pdfPath: string, pdf?: object): {
+export function compileTypst(typPath: string, pdfPath: string, pdf?: object, config?: {
+    rootDir?: string;
+    paths?: {
+        content?: string;
+    };
+}): {
     ok: boolean;
     message: string;
     findings: object[];

package/types/engine/pdf-render.d.mts

@@ -85,6 +85,9 @@ export function stripHtmlComments(markdown: string): string;
  *   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.
@@ -124,6 +127,7 @@ export function markdownToTypst(markdown: string, opts?: {
     anchorPrefix?: string | undefined;
     findings?: object[] | undefined;
     file?: string | undefined;
+    runs?: import("./content-scripts.mjs").RunContext | undefined;
     bodyLine?: number | undefined;
     bodyColumn?: number | undefined;
     lineMap?: {
@@ -228,9 +232,17 @@ export function crossBookReference(inner: string, away: {
  * 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(): string;
+export function bookTypstPreamble(runs?: import("./content-scripts.mjs").RunContext, families?: {
+    serif?: string;
+    sans?: string;
+    mono?: string;
+}): string;
 /**
  * The whole book, as one Typst document.
  *
@@ -345,9 +357,11 @@ export function bookTypstPreamble(): string;
  * @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({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners, maps, coverImage, authors, copyright, license, index, }?: {
+export function renderBook({ plan, bodies, title, subtitle, front, fonts, version, preamble, banners, maps, coverImage, authors, copyright, license, index, runs, }?: {
     plan: object;
     bodies: Map<string, string>;
     title: string;
@@ -369,6 +383,7 @@ export function renderBook({ plan, bodies, title, subtitle, front, fonts, versio
     copyright?: string | undefined;
     license?: string | undefined;
     index?: object | undefined;
+    runs?: import("./content-scripts.mjs").RunContext | undefined;
 }): string;
 /**
  * Point every internal link at a label the document actually declares.