@heroiclands/package-build 25.5.4 → 25.5.5

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

@@ -37,12 +37,13 @@ export function scanVerse(source: string, { checkWorks }?: {
  * Offsets are UTF-16 positions relative to body. Delimiters and indentation are
  * layout ranges; source newlines inside a logical line contribute one space.
  * @param {string} body - Authored verse body.
- * @param {{inline?: boolean, footnotes?: ReadonlySet<string>}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels.
+ * @param {{inline?: boolean, footnotes?: ReadonlySet<string>, sourceOffsets?: number[]}} [options] - Inline quotations have no cantos; footnotes are same-note definition labels; sourceOffsets maps projected body positions to authored offsets, including the end.
  * @returns {VerseModel} The shared structure with offsets relative to the body.
  */
-export function parseVerse(body: string, { inline, footnotes }?: {
+export function parseVerse(body: string, { inline, footnotes, sourceOffsets }?: {
     inline?: boolean;
     footnotes?: ReadonlySet<string>;
+    sourceOffsets?: number[];
 }): VerseModel;
 /**
  * Validate a quoted verse span using its original source coordinates.
@@ -271,6 +272,14 @@ export type VerseBlock = {
      * - Authored verse body.
      */
     body: string;
+    /**
+     * - Body without Markdown container prefixes.
+     */
+    logicalBody: string;
+    /**
+     * - Logical UTF-16 offsets mapped to authored body offsets, including the end.
+     */
+    bodyOffsets: number[];
     /**
      * - Logical structure relative to the body.
      */

package/types/engine/core-report.d.mts

@@ -4,7 +4,7 @@
  * @param {Iterable<Record<string, any>>} records - Index records.
  * @param {{language?: string}} [options] - A language to report alone, by its
  *   name, shortcode or reference slug whether or not it states `data.core`.
- * @returns {{concepts: number, languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
+ * @returns {{concepts: number, notCovered: string[], languages: Array<{name: string, language: string, core: boolean, total: number, covered: number, missing: Array<{group: string, count: number, total: number, concepts: Array<{id: string, gloss: string}>}>}>}|{problem: string, about: string}}
  *   The report, or the problem when there is no concept list or the language
  *   asked for is none.
  */
@@ -12,6 +12,7 @@ export function coreReport(records: Iterable<Record<string, any>>, { language }?
     language?: string;
 }): {
     concepts: number;
+    notCovered: string[];
     languages: Array<{
         name: string;
         language: string;
@@ -36,10 +37,13 @@ export function coreReport(records: Iterable<Record<string, any>>, { language }?
  * A core report as text: one block per language, its missing concepts under
  * their groups with counts, each concept's id and gloss tab-separated.
  *
- * @param {{concepts: number, languages: Array<object>}} report - A report from {@link coreReport}.
+ * The default report ends with the names of languages it does not measure.
+ *
+ * @param {{concepts: number, notCovered: string[], languages: Array<object>}} report - A report from {@link coreReport}.
  * @returns {string} The text, ending in a newline.
  */
 export function coreReportText(report: {
     concepts: number;
+    notCovered: string[];
     languages: Array<object>;
 }): string;

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

@@ -1,5 +1,5 @@
 /**
- * The genders every `data.names.given` states a list for.
+ * The genders a mapped `data.names.given` states a list for.
  *
  * A function rather than a `const`: `note-vocabulary.mjs` reads it while the
  * module graph is still evaluating.
@@ -47,7 +47,7 @@ export function namesProblems(names: unknown, lookVocabulary: Readonly<Record<st
  * keys cannot: a pattern that does not parse, a placeholder naming no list, a
  * list no pattern names, a list name a placeholder cannot spell, an empty list
  * of patterns or of names, an empty name, a pattern or given list keyed by no
- * gender, and a missing `female` or `male` list. Each is located at the pattern, list, entry or key at fault.
+ * gender, and a missing `female` or `male` list in a gender map. Each is located at the pattern, list, entry or key at fault.
  *
  * @param {object} note - The note: `file`, `raw` and parsed `fm`.
  * @param {Readonly<Record<string, readonly {value: string}[]>>} lookVocabulary -
@@ -70,8 +70,8 @@ export function namesFindings(note: object, lookVocabulary: Readonly<Record<stri
     value: string;
 }[]>>): object[];
 /**
- * The given names a gender draws from: its own list, or every given list
- * together where it has none.
+ * The given names a gender draws from: the shared list, its own list, or
+ * every given list together where it has none.
  *
  * @param {object} names - Checked `data.names`.
  * @param {string} gender - A gender word.
@@ -79,8 +79,20 @@ export function namesFindings(note: object, lookVocabulary: Readonly<Record<stri
  */
 export function givenNames(names: object, gender: string): string[];
 /**
- * A name drawn from a language's lists: one of the gender's patterns, where it
- * has more than one, then each placeholder an even draw from its list.
+ * A name's selected literal and placeholder parts. One of the gender's
+ * patterns is selected first, then each placeholder is an even draw from its
+ * source list.
+ *
+ * @param {object} names - Checked `data.names`.
+ * @param {string} gender - A gender word.
+ * @param {() => number} next - A stream of numbers in `[0, 1)`.
+ * @returns {(PatternPart & {text: string})[]} The selected parts in pattern order.
+ */
+export function drawNameParts(names: object, gender: string, next: () => number): (PatternPart & {
+    text: string;
+})[];
+/**
+ * A name drawn from a language's lists.
  *
  * @param {object} names - Checked `data.names`.
  * @param {string} gender - A gender word.

package/types/engine/npc-generate.d.mts

@@ -57,6 +57,8 @@ export function appearanceParagraph({ name, age, gender, height, frame, appearan
  *   by `namesProblems`.
  * @param {string} [context.language] - The language's Address, for an error
  *   about a name that does not fit.
+ * @param {string} [context.languageCode] - The language code under which a
+ *   generated name's distinct source form is retained.
  * @param {string} [context.seed] - Text joined to the spec's own seed, to draw a
  *   different person from the same spec.
  * @param {unknown} [context.currentDate] - The setting's neutral current date, defaulting to "720.1".
@@ -74,6 +76,7 @@ export function generateNpc(spec: object, context: {
     profile: object;
     names: object;
     language?: string | undefined;
+    languageCode?: string | undefined;
     seed?: string | undefined;
     currentDate?: unknown;
     dateContext?: object | undefined;

package/types/engine/page-breaks.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Read page-break markers before any surface rewrites their source.
+ * Code, HTML examples and entire verse divs remain literal. Parser ranges
+ * retain list and quote membership, including lazy continuation lines.
+ * @param {string} source - Authored Markdown body.
+ * @returns {{breaks: Array<{line: number, column: number}>, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanPageBreaks(source: string): {
+    breaks: Array<{
+        line: number;
+        column: number;
+    }>;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};
+/**
+ * Omit valid page breaks on a screen, preserving the surrounding block boundaries.
+ * @param {string} source - Markdown body.
+ * @returns {string} Markdown without valid page-break lines.
+ */
+export function omitPageBreaks(source: string): string;
+/**
+ * Produce the book's page-break token, leaving ordinary thematic breaks alone.
+ * @param {import("markdown-it")} md - The book parser.
+ * @returns {void}
+ */
+export function pageBreakPlugin(md: typeof import("markdown-it")): void;

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

@@ -98,6 +98,7 @@ export function stripHtmlComments(markdown: string): string;
  * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - From
  *   table expansion, mapping each line handed in back to the line an author
  *   wrote.
+ * @param {boolean} [opts.pageBreaks] - Internal: whether this slice remains at the note top level.
  * @param {boolean} [opts.prepared] - Whether this body has been through the
  *   passes that resolve a wikilink, an embed and an inline expression. A note's
  *   has; a front-matter file's and a prose file's have not, and markup of theirs
@@ -138,6 +139,7 @@ export function markdownToTypst(markdown: string, opts?: {
         line: number;
         generated: boolean;
     }[] | undefined;
+    pageBreaks?: boolean | undefined;
     prepared?: boolean | undefined;
     url?: string | undefined;
     elsewhere?: {

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

@@ -306,6 +306,7 @@ export function sitePageDecorator(config: any, index: any): (data: any, page: an
  * @param {object} [options] - Options.
  * @param {object} [options.config] - A resolved configuration; loaded when
  *   omitted.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @param {Map<string, object[]>} [options.sqlTables] - Prepared `sql` results,
  *   keyed by the note's absolute file, from
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
@@ -322,8 +323,9 @@ export function sitePageDecorator(config: any, index: any): (data: any, page: an
  *   against the rest of the build, or returns `null` when its address, name
  *   or type changed and the whole site must be built again.
  */
-export function buildSite({ config, sqlTables }?: {
+export function buildSite({ config, sqlTables, progress }?: {
     config?: object | undefined;
+    progress?: ((message: string) => void) | undefined;
     sqlTables?: Map<string, object[]> | undefined;
 }): {
     gates: object;

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

@@ -50,19 +50,21 @@ export function writeThemeFiles(out: string, staticDir?: string): string[];
  * @param {string} [options.staticDir] - The theme's own files, copied first.
  * @param {ReadonlySet<string>} [options.only] - The addresses of the pages to
  *   draw again into a site already written. Nothing else is touched.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {{files: string[], pages: string[], reachable: string[],
  *   findings: object[]}} Every file written, the address of every page, the
  *   address of each page reachable from the homepage, and the layouts' findings.
  * @throws {Error} When a page's address is outside the site, or a site served
  *   under a path asks for a sitemap index.
  */
-export function writeSite({ site, pages, out, report, staticDir, only }: {
+export function writeSite({ site, pages, out, report, staticDir, only, progress, }: {
     site: object;
     pages: readonly object[];
     out: string;
     report?: ((finding: import("./site-theme.mjs").Finding) => void) | undefined;
     staticDir?: string | undefined;
     only?: ReadonlySet<string> | undefined;
+    progress?: ((message: string) => void) | undefined;
 }): {
     files: string[];
     pages: string[];
@@ -147,6 +149,7 @@ export function deliverSiteFonts(config: object, out: string): {
  * @param {string} options.out - The directory the site is written to, which
  *   is the package's own directory under the deployed root.
  * @param {number} [options.year] - The year the footer states.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {Promise<{built: object, written: object|null, fonts: object|null,
  *   site?: object, pages?: object[], pageOf?: (entry: object) => object}>}
  *   What the build found, and, when it found nothing that stops it, what was
@@ -154,10 +157,11 @@ export function deliverSiteFonts(config: object, out: string): {
  *   becomes its page. `written` is `null` when a gate fired.
  * @throws {Error} When the site's settings or its cached menu cannot be read.
  */
-export function buildPackageSite({ config, out, year }: {
+export function buildPackageSite({ config, out, year, progress }: {
     config: object;
     out: string;
     year?: number | undefined;
+    progress?: ((message: string) => void) | undefined;
 }): Promise<{
     built: object;
     written: object | null;

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

@@ -73,6 +73,7 @@ export function indexSite(where: {
  *   `site.search` in the configuration. Default `true`.
  * @param {SiteIndexer} [options.indexer] - What builds it. Default
  *   {@link indexSite}.
+ * @param {(message: string) => void} [options.progress] - Build phase summaries.
  * @returns {Promise<{files: string[], search: {dir: string, pages: number}|null}>}
  *   The files written, and the index — where it is and how many pages it
  *   holds — or `null` when none was built.
@@ -81,12 +82,13 @@ export function indexSite(where: {
  *   under the prefix; or, located at the rendered site, when the indexer
  *   fails.
  */
-export function writeSiteRoot({ pkg, base, out, search, indexer }: {
+export function writeSiteRoot({ pkg, base, out, search, indexer, progress, }: {
     pkg: string;
     base?: string | undefined;
     out: string;
     search?: boolean | undefined;
     indexer?: SiteIndexer | undefined;
+    progress?: ((message: string) => void) | undefined;
 }): Promise<{
     files: string[];
     search: {

package/types/engine/site-serve-http.d.mts

@@ -0,0 +1 @@
+export {};

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

@@ -9,16 +9,19 @@
  *   directory above `out` by default; `out` itself for a site served at `/`.
  * @param {string} [options.host] - The address to listen on.
  * @param {number} [options.port] - The port; `0` takes any free one.
- * @param {boolean} [options.search] - Build the search index after the first
+ * @param {boolean} [options.search] - Build the search index with each whole
  *   build, where the site has one.
  * @param {number} [options.year] - The year the footer states.
- * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown}) => void} [options.report] -
- *   Told of each build: `built` for a whole build, `page` for one note's page,
+ * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown, message?: string, fatal?: boolean}) => void} [options.report] -
+ *   Told of progress (`message`) and each build: `built` for a whole build, `page` for one note's page,
  *   `theme` for the theme, `failed` with what the build found, `error` with
  *   what it threw.
- * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>}>}
- *   The address of the site's home page, how to stop serving, and a promise
- *   for the moment every change seen so far has been written.
+ * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>, done: Promise<void>}>}
+ *   Resolves as soon as HTTP listens, before the first build. The address of
+ *   the site's home page, how to stop serving, and a promise for the initial
+ *   build and every change seen so far to finish. Failed builds are reported
+ *   through `report` and leave the last successful site in service. `done`
+ *   resolves on close and rejects if HTTP stops unexpectedly.
  */
 export function serveSite({ config, out, root, host, port, search, year, report, }: {
     config: object;
@@ -34,11 +37,14 @@ export function serveSite({ config, out, root, host, port, search, year, report,
         files?: string[];
         findings?: object[];
         error?: unknown;
+        message?: string;
+        fatal?: boolean;
     }) => void) | undefined;
 }): Promise<{
     url: string;
     close: () => Promise<void>;
     settled: () => Promise<void>;
+    done: Promise<void>;
 }>;
 /** The address a served page listens on for the server's reloads. */
 export const RELOAD_PATH: "/__package-build/reload";

package/types/engine/verse-metre.d.mts

@@ -73,7 +73,7 @@ export function metreMessage({ min, max }: {
  * @param {ReadonlyArray<{start: number, end: number, indent: string, attributes: Record<string, string>, classes: string[]}>} blocks -
  *   The divs, from {@link module:engine/content-verse.scanVerse}.
  * @param {string[]} lines - The source's lines.
- * @param {{languages?: Readonly<Record<string, {tag: string}>>, metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
+ * @param {{languages?: Readonly<Record<string, {tag: string}>>, metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>, metreBooks?: ReadonlyMap<string, MetreBook>, lexicons?: ReadonlyMap<string, unknown>, referenceName?: (target: string) => string|undefined, attributeColumns: (line: string, key: string) => {key: number, value: number}}} ctx -
  *   The metres and books, and how the div says its columns and where its
  *   keys sit.
  * @returns {{errors: object[], warnings: object[]}} The findings at 1-based
@@ -92,6 +92,7 @@ export function metreFindings(blocks: ReadonlyArray<{
     metres?: ReadonlyMap<string, import("./metre-declaration.mjs").Metre>;
     metreBooks?: ReadonlyMap<string, MetreBook>;
     lexicons?: ReadonlyMap<string, unknown>;
+    referenceName?: (target: string) => string | undefined;
     attributeColumns: (line: string, key: string) => {
         key: number;
         value: number;

package/types/engine/verse-regions.d.mts

@@ -51,6 +51,14 @@ export type VerseRegion = {
      * - Authored body bytes.
      */
     body: string;
+    /**
+     * - Body without Markdown container prefixes.
+     */
+    logicalBody: string;
+    /**
+     * - Logical UTF-16 offsets mapped to authored body offsets, including the end.
+     */
+    bodyOffsets: number[];
     /**
      * - Authored values.
      */