@heroiclands/package-build 23.12.6 → 23.12.8

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-coverage.d.mts

@@ -37,7 +37,7 @@ export function coverage({ books, corpus, unprinted, mode, locate }: {
     }>;
     corpus: object[];
     unprinted?: object[] | undefined;
-    mode?: "error" | "off" | "warning" | undefined;
+    mode?: "warning" | "error" | "off" | undefined;
     locate?: ((record: object) => {
         file?: string;
         line?: number;

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.

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

@@ -0,0 +1,89 @@
+/**
+ * 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: string, { context, bodyLine, bodyColumn, syntax }?: {
+    context?: import("./content-scripts.mjs").RunContext | undefined;
+    bodyLine?: number | undefined;
+    bodyColumn?: number | undefined;
+    syntax?: import("./content-session.mjs").ContentSyntax | undefined;
+}): RecordRun[];
+/**
+ * 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: Record<string, any>): string | 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: Iterable<Record<string, any>>): RunRow[];
+/** Every column of the `runs` relation, in order. */
+export const RUN_COLUMNS: readonly string[];
+/**
+ * One run as an index record carries it.
+ */
+export type RecordRun = {
+    /**
+     * - The construct.
+     */
+    kind: "span" | "block" | "poetry";
+    /**
+     * - The language it is set in, as written: its
+     * own `lang=`, else the one the div or fence around it states.
+     */
+    lang: string | null;
+    /**
+     * - The BCP 47 tag it resolves to, or null.
+     */
+    tag: string | null;
+    /**
+     * - Its font, as written and inherited the same way.
+     */
+    font: string | null;
+    /**
+     * - Its map, as written and inherited the same way.
+     */
+    map: string | null;
+    /**
+     * - 1-based file line of its opening.
+     */
+    line: number;
+    /**
+     * - 1-based UTF-16 file column of its opening.
+     */
+    column: number;
+};
+export type RunRow = RecordRun & {
+    owner: string | null;
+};

package/types/engine/run-words.d.mts

@@ -0,0 +1,86 @@
+/**
+ * A word as it is compared: NFC, lowercase, `’` read as `'`.
+ *
+ * @param {string} word - The word.
+ * @returns {string} Its folded form.
+ */
+export function foldWord(word: string): string;
+/**
+ * The words a language note accepts of its own: its forms, and what its
+ * plural rows, verb pattern and replacing suffixes derive from them.
+ *
+ * @param {Record<string, any>} data - The language note's `data`.
+ * @returns {Set<string>} The words, folded.
+ */
+export function lexiconWords(data: Record<string, any>): Set<string>;
+/**
+ * The words of every name a language note registers under a tongue other than
+ * `translation`.
+ *
+ * @param {Record<string, any>|undefined} data - The language note's `data`.
+ * @returns {Set<string>} The words, folded.
+ */
+export function registeredNameWords(data: Record<string, any> | undefined): Set<string>;
+/**
+ * What a mapped run's words are checked against, for one language.
+ *
+ * @typedef {object} WordBook
+ * @property {string} language - The language's configured name, as `lang=`
+ *   writes it.
+ * @property {(word: string) => boolean} accepts - Whether a folded word is
+ *   one of the language's.
+ */
+/**
+ * Each configured language's word book: one per language whose `note` names a
+ * language note.
+ *
+ * @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, WordBook>} The books by language name.
+ */
+export function wordBooksFromRecords(records: Iterable<Record<string, any>> | undefined, config?: {
+    languages?: Readonly<Record<string, {
+        tag: string;
+        note?: string;
+    }>>;
+    contentPackage?: string;
+}): Map<string, WordBook>;
+/**
+ * The words of a text its book does not accept, each once, at the offset of
+ * its first character: a compound not accepted whole gives each part that is
+ * not.
+ *
+ * @param {string} text - The text, with no escapes.
+ * @param {WordBook} book - The language's book.
+ * @param {Set<string>} [said] - The folded words already reported in this
+ *   run, which are not reported again; updated.
+ * @returns {Array<{offset: number, word: string}>} The words, in order.
+ */
+export function unknownWords(text: string, book: WordBook, said?: Set<string>): Array<{
+    offset: number;
+    word: string;
+}>;
+/**
+ * The finding for a word of a mapped run that is not a word of its language.
+ *
+ * @param {string} word - The word as written.
+ * @param {string} language - The language as `lang=` names it.
+ * @returns {string} The message.
+ */
+export function unknownWordMessage(word: string, language: string): string;
+/**
+ * What a mapped run's words are checked against, for one language.
+ */
+export type WordBook = {
+    /**
+     * - The language's configured name, as `lang=`
+     * writes it.
+     */
+    language: string;
+    /**
+     * - Whether a folded word is
+     * one of the language's.
+     */
+    accepts: (word: string) => boolean;
+};

package/types/engine/script-font-delivery.d.mts

@@ -0,0 +1,134 @@
+/**
+ * The faces the package's notes set text in with `font=`, read from the
+ * notes themselves: every Markdown file under the content tree that writes
+ * `font=` is scanned for its runs.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @returns {ReadonlySet<string>} The slugs of the faces used.
+ */
+export function facesUsed(config: DeliveryConfig, installed: import("./script-fonts.mjs").ScriptFonts): ReadonlySet<string>;
+/**
+ * The files a target receives, as paths relative to the fonts package root.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {string[]} formats - The font formats the target uses: `woff2`, `ttf`.
+ * @returns {{root: string, version: string, files: string[]}|undefined} The
+ *   files, sorted: `fonts.css`, `LICENSE` and every file in `fonts/` of a
+ *   listed format. `undefined` when the consumer ships none.
+ */
+export function scriptFontFiles(config: DeliveryConfig, formats: string[]): {
+    root: string;
+    version: string;
+    files: string[];
+} | undefined;
+/**
+ * The fonts package's stylesheet as a target stages it: each `@font-face`
+ * `src` lists only the files staged beside it, so no browser asks for a
+ * format the target does not carry. A `local(…)` source stays, and a face
+ * left with no source is dropped.
+ *
+ * @param {string} css - The stylesheet as the package publishes it.
+ * @param {ReadonlySet<string>} staged - The staged files, relative to the
+ *   stylesheet: `fonts/SemaronKuriale-Regular.woff2`.
+ * @returns {string} The stylesheet to stage.
+ */
+export function stagedStylesheet(css: string, staged: ReadonlySet<string>): string;
+/**
+ * Copy the delivered files into a directory, keeping their relative layout so
+ * the stylesheet's `url("fonts/…")` resolves from where it lands. The
+ * stylesheet is rewritten by {@link stagedStylesheet} to name only the files
+ * copied with it.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {string} dest - The directory to fill; created when there is
+ *   something to put in it.
+ * @param {string[]} formats - The font formats the target uses.
+ * @returns {number} How many files were written; 0 when the consumer ships none.
+ */
+export function copyScriptFonts(config: DeliveryConfig, dest: string, formats: string[]): number;
+/**
+ * Whether the package ships what its manifest and stylesheet promise: the
+ * stylesheet, the licence and every file the manifest lists.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {{file: string, severity: "error", message: string}[]} One finding
+ *   per missing file, located at the manifest; empty when the consumer ships none.
+ */
+export function checkScriptFonts(config: DeliveryConfig): {
+    file: string;
+    severity: "error";
+    message: string;
+}[];
+/**
+ * The site param naming the stylesheet, relative to the site root.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {string|undefined} The versioned address, or `undefined` when the
+ *   site ships no fonts.
+ */
+export function siteFontsParam(config: DeliveryConfig): string | undefined;
+/**
+ * The directory under the Hugo static tree that holds this version's fonts.
+ *
+ * @param {string} version - The fonts package's version.
+ * @returns {string} The POSIX path, relative to `build/hugo/static`.
+ */
+export function siteFontsDestination(version: string): string;
+/**
+ * The manifest `styles`, with the fonts' stylesheet named after the base sheet.
+ *
+ * @param {object} options
+ * @param {unknown} options.styles - The `styles` so far, base sheet included.
+ * @param {"system"|"module"} options.artifact - Which artifact is shipped.
+ * @param {boolean} options.delivered - Whether the module carries the fonts.
+ * @returns {unknown} The `styles` to emit.
+ */
+export function withScriptFontStyle({ styles, artifact, delivered: carried }: {
+    styles: unknown;
+    artifact: "system" | "module";
+    delivered: boolean;
+}): unknown;
+/**
+ * The directory of TTFs a book's compiler searches.
+ *
+ * @param {DeliveryConfig} config - The resolved configuration.
+ * @returns {string|undefined} The package's `fonts/` directory, or `undefined`
+ *   when the consumer ships no fonts.
+ */
+export function typstScriptFontPath(config: DeliveryConfig): string | undefined;
+/**
+ * Where the files land in the staged Foundry module, relative to its root.
+ *
+ * @type {string}
+ */
+export const STAGED_FONTS_DIR: string;
+/**
+ * Where the files land in the Hugo static tree, relative to `build/hugo/static`,
+ * beneath a directory per version.
+ *
+ * @type {string}
+ */
+export const SITE_FONTS_DIR: string;
+/**
+ * The part of a resolved configuration delivery reads.
+ */
+export type DeliveryConfig = {
+    /**
+     * - The consuming package's root.
+     */
+    rootDir?: string | undefined;
+    /**
+     * - Where its notes are; relative to
+     * `rootDir` unless absolute.
+     */
+    paths?: {
+        content?: string;
+    } | undefined;
+    /**
+     * - Its languages.
+     */
+    languages?: Readonly<Record<string, {
+        tag: string;
+    }>> | undefined;
+};

package/types/engine/script-fonts.d.mts

@@ -0,0 +1,168 @@
+/**
+ * One code point a face draws, as `fonts.json` lists it.
+ *
+ * @typedef {object} FaceCodepoint
+ * @property {string} codepoint - `U+` and the hexadecimal code point.
+ * @property {string} glyph - The glyph's name in the face.
+ * @property {string} kind - What it is: `letter`, `numeral`, `mark` and so on.
+ */
+/**
+ * One entry of `fonts.json`.
+ *
+ * @typedef {object} FontEntry
+ * @property {string} [name] - Its unique key; `family` when absent.
+ * @property {string} family - The CSS and Typst font family.
+ * @property {string} class - The class that sets text in it, `hl-<slug>`.
+ * @property {Record<string, string>} files - Its font files, by format.
+ * @property {string} direction - `ltr` or `rtl`.
+ * @property {string[]} features - OpenType features it turns on.
+ * @property {FaceCodepoint[]} [codepoints] - Every code point it draws.
+ */
+/**
+ * A face as a run reads it.
+ *
+ * @typedef {object} Face
+ * @property {string} slug - What `font=` names it by: its class without `hl-`.
+ * @property {string} family - The CSS and Typst font family.
+ * @property {string} class - The class that sets text in it.
+ * @property {string} direction - `ltr` or `rtl`.
+ * @property {string[]} features - OpenType features it turns on.
+ * @property {ReadonlySet<number>} draws - Every code point it draws.
+ */
+/**
+ * The installed fonts package, as a consumer sees it.
+ *
+ * @typedef {object} ScriptFonts
+ * @property {string} root - The package's directory.
+ * @property {string} version - Its `package.json` version.
+ * @property {{families: FontEntry[]}|undefined} manifest - Its `fonts.json`,
+ *   `undefined` when the installed version ships none.
+ * @property {Map<string, Face>} faces - Each face by its slug, in manifest
+ *   order; empty without a manifest.
+ */
+/**
+ * The slug `font=` names a face by: its class without the `hl-` prefix.
+ *
+ * @param {FontEntry} entry - A `fonts.json` entry.
+ * @returns {string|undefined} The slug, or `undefined` for an entry with no class.
+ */
+export function faceSlug(entry: FontEntry): string | undefined;
+/**
+ * The fonts package the consumer at `rootDir` installed.
+ *
+ * @param {string} rootDir - The consuming package's root, holding its
+ *   `package.json`.
+ * @returns {ScriptFonts|undefined} The package, or `undefined` when the
+ *   consumer has not installed it.
+ * @throws {Error} When the installed `fonts.json` is not readable JSON, or
+ *   holds no `families` list.
+ */
+export function resolveScriptFonts(rootDir: string): ScriptFonts | undefined;
+/** The npm name of the fonts package. */
+export const FONTS_PACKAGE: "@heroiclands/fonts";
+/** The manifest the fonts package publishes at its root. */
+export const FONTS_MANIFEST: "fonts.json";
+/**
+ * One code point a face draws, as `fonts.json` lists it.
+ */
+export type FaceCodepoint = {
+    /**
+     * - `U+` and the hexadecimal code point.
+     */
+    codepoint: string;
+    /**
+     * - The glyph's name in the face.
+     */
+    glyph: string;
+    /**
+     * - What it is: `letter`, `numeral`, `mark` and so on.
+     */
+    kind: string;
+};
+/**
+ * One entry of `fonts.json`.
+ */
+export type FontEntry = {
+    /**
+     * - Its unique key; `family` when absent.
+     */
+    name?: string | undefined;
+    /**
+     * - The CSS and Typst font family.
+     */
+    family: string;
+    /**
+     * - The class that sets text in it, `hl-<slug>`.
+     */
+    class: string;
+    /**
+     * - Its font files, by format.
+     */
+    files: Record<string, string>;
+    /**
+     * - `ltr` or `rtl`.
+     */
+    direction: string;
+    /**
+     * - OpenType features it turns on.
+     */
+    features: string[];
+    /**
+     * - Every code point it draws.
+     */
+    codepoints?: FaceCodepoint[] | undefined;
+};
+/**
+ * A face as a run reads it.
+ */
+export type Face = {
+    /**
+     * - What `font=` names it by: its class without `hl-`.
+     */
+    slug: string;
+    /**
+     * - The CSS and Typst font family.
+     */
+    family: string;
+    /**
+     * - The class that sets text in it.
+     */
+    class: string;
+    /**
+     * - `ltr` or `rtl`.
+     */
+    direction: string;
+    /**
+     * - OpenType features it turns on.
+     */
+    features: string[];
+    /**
+     * - Every code point it draws.
+     */
+    draws: ReadonlySet<number>;
+};
+/**
+ * The installed fonts package, as a consumer sees it.
+ */
+export type ScriptFonts = {
+    /**
+     * - The package's directory.
+     */
+    root: string;
+    /**
+     * - Its `package.json` version.
+     */
+    version: string;
+    /**
+     * - Its `fonts.json`,
+     * `undefined` when the installed version ships none.
+     */
+    manifest: {
+        families: FontEntry[];
+    } | undefined;
+    /**
+     * - Each face by its slug, in manifest
+     * order; empty without a manifest.
+     */
+    faces: Map<string, Face>;
+};

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

@@ -230,7 +230,7 @@ export function pageDestination(page: {
     slug: string;
 }): string;
 /** Transform one content page without writing the site mount. */
-export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, figuresByAddress, events, drawings, }: {
+export function renderSitePage(page: any, { index, foreign, universe, pass, decorate, linkable, sqlTables, config, artIndex, figuresByAddress, events, drawings, runs, }: {
     index: any;
     foreign: any;
     universe: any;
@@ -243,6 +243,7 @@ export function renderSitePage(page: any, { index, foreign, universe, pass, deco
     figuresByAddress?: Map<any, any> | undefined;
     events: any;
     drawings?: Map<any, any> | undefined;
+    runs?: import("./content-scripts.mjs").RunContext | undefined;
 }): {
     page: any;
     body: string;

package/types/engine/site-root.d.mts

@@ -18,15 +18,23 @@
  */
 export function noindexHeaders(): string[];
 /**
- * The `_headers` file's contents: the `noindex` rules, and nothing else.
+ * The `_headers` file's contents: the `noindex` rules, and the script fonts'
+ * cache rule when the site carries them.
  *
  * No `Cache-Control` is pinned on the prefix root. It is the homepage, and a
  * lifetime on it would hold a stale copy at the most-linked address after a
- * deploy; Pages' own defaults for a page apply.
+ * deploy; Pages' own defaults for a page apply. The fonts sit under a path
+ * that names their version, so a year's lifetime never serves a stale file.
  *
+ * @param {object} [options] - Options.
+ * @param {string} [options.pkg] - The content package, which is the prefix.
+ * @param {boolean} [options.fonts] - Whether the site carries the fonts.
  * @returns {string} The file's contents.
  */
-export function headers(): string;
+export function headers({ pkg, fonts }?: {
+    pkg?: string | undefined;
+    fonts?: boolean | undefined;
+}): string;
 export function indexSite(where: {
     site: string;
     output: string;