@heroiclands/package-build 25.5.4 → 25.6.0

package/types/engine/holdings.d.mts

@@ -47,13 +47,45 @@ export function foreignHoldingsNodes(foreignIndex: Map<string, object> | undefin
 export function holdingsPages(nodes: Iterable<HoldingsNode | null>, { governmentNodes }?: {
     governmentNodes?: Iterable<HoldingsNode | null> | undefined;
 }): Map<string, Holdings>;
+/**
+ * Whether a record's `data.government` came from a parent rather than its own
+ * note.
+ *
+ * @param {object} record - An index record.
+ * @returns {boolean} True for a district that inherited its government.
+ */
+export function governmentInherited(record: object): boolean;
+/**
+ * Give each district that states no government its parent's.
+ *
+ * A `place/district` falls under the government of the place it stands
+ * within. One stating no `data.government` key takes the value of its nearest
+ * parent that states the key, walking `data.parents` breadth first, in the
+ * order written, through any parent that states none, and never visiting a
+ * place twice. An explicit value on the district, `null` (complete anarchy)
+ * included, is its own and is kept; a parent's explicit `null` is inherited as
+ * anarchy. Every reader of the index — the Governed by and Governed places
+ * sections, the "missing government" advisory, a consumer of the published
+ * index — then reads the effective government at `data.government`.
+ *
+ * @param {object[]} records - Content-index records, edited in place.
+ * @param {object} [opts]
+ * @param {(key: string) => object|undefined} [opts.foreignRecord] - A fetched
+ *   index's record by canonical Address, for a parent in a dependency.
+ * @returns {void}
+ */
+export function inheritDistrictGovernments(records: object[], { foreignRecord }?: {
+    foreignRecord?: ((key: string) => object | undefined) | undefined;
+}): void;
 /**
  * Advise when a place with an authored positive population omits government.
  * Missing, null or zero population establishes no inhabited population.
  * Property presence distinguishes omitted government from explicit null,
  * which means complete anarchy. Non-null values are validated by the declared
- * affiliation reference field. Neither geographic containment nor tenure
- * supplies this fact, and the rule is independent of place subtype.
+ * affiliation reference field. Tenure never supplies this fact, and
+ * containment supplies it only to a district, which the content index gives
+ * its nearest parent's government (see {@link inheritDistrictGovernments}), so
+ * a district under a governed place is never advised.
  *
  * @param {object} note - The note with parsed frontmatter and raw source.
  * @returns {object[]} Located warning findings.

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

@@ -122,7 +122,8 @@ export function recordPath(record: Record<string, any>): string;
  * since a note declaring its own is a hard error — and it matches what
  * the content-table expander puts on the same field, so a query reads the same
  * value from either. `file` namespaces the note's place in the tree, again
- * matching the expander's `file.*`.
+ * matching the expander's `file.*`. `officeHolders` lists, on a body, the
+ * living beings whose own standing names each of its offices.
  *
  * Both are checked rather than assumed: `folder` is real frontmatter on most
  * notes, so the neighbouring names are close enough to a real key that a silent

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/language-terms.d.mts

@@ -94,7 +94,11 @@ export const JOIN_MEETINGS: readonly string[];
  * letters between, `drop` loses the first, `double` doubles the consonant.
  */
 export const JOIN_RULES: readonly string[];
-/** What a written mark says of its letter. */
+/**
+ * What a written mark says of its letter: `stress` falls on it, `length` holds
+ * it longer, `apart` says it apart from its neighbour, and `quality` changes
+ * which vowel is said.
+ */
 export const MARK_KINDS: readonly string[];
 /** How many of a mark a word may carry: `one` at most, or `any` number. */
 export const MARK_LIMITS: readonly string[];

package/types/engine/markdown-blocks.d.mts

@@ -3,6 +3,10 @@
  * and must not be modified; an `inline` token carries no `children`.
  *
  * @param {unknown} source - Markdown.
+ * @param {object} [options] - Optional block projection.
+ * @param {boolean} [options.footnotes=false] - Include footnote definition containers.
  * @returns {readonly import("markdown-it").Token[]} The block tokens, in order.
  */
-export function blockTokens(source: unknown): readonly import("markdown-it").Token[];
+export function blockTokens(source: unknown, { footnotes }?: {
+    footnotes?: boolean | undefined;
+}): readonly import("markdown-it").Token[];

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/office-holders.d.mts

@@ -1,3 +1,36 @@
+/**
+ * A note's identity across its systems: `package-type-shortcode`, lowercased.
+ *
+ * A body's Item and its journal carry one page, and a being names the body by
+ * its `note` Address, so the system is left out.
+ *
+ * @param {{package?: string, type?: string, shortcode?: string}} tuple
+ * @returns {string} The key, or `""` where a part is missing.
+ */
+export function officeBodyKey(tuple: {
+    package?: string;
+    type?: string;
+    shortcode?: string;
+}): string;
+/**
+ * Each body's offices with the living beings that hold them.
+ *
+ * Nothing is authored on the office for this: a being states the post it holds
+ * in its own `data.affiliations.<body>.office`, and this collects, for every
+ * office in a body's `governance.offices`, each being naming it. A being whose
+ * `data.died` is set holds nothing, so a former holder drops out and a vacant
+ * office lists no one. A post the body does not declare is the standing check's
+ * finding and is listed nowhere.
+ *
+ * Offices keep the body's declared order; holders are ordered by name.
+ *
+ * @param {object[]} records - Content-index records; only note records are
+ *   read.
+ * @returns {Map<string, Map<string, object[]>>} Body identity
+ *   (`package-type-shortcode`) → office → the holding beings' records, for every
+ *   body with at least one held office.
+ */
+export function officeHolders(records: object[]): Map<string, Map<string, object[]>>;
 /**
  * Validate one affiliation's office roster against dated beings in the corpus.
  * @param {object} note

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

@@ -0,0 +1,38 @@
+/**
+ * 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;
+/**
+ * Preserve refused markers as literal Markdown before the book slices blocks.
+ * A slice must not make a marker eligible by discarding its original neighbour.
+ * Findings are collected from the original source before this rewrite.
+ * @param {string} source - Complete Markdown body, before splitting containers.
+ * @returns {string} Markdown with invalid markers escaped for literal rendering.
+ */
+export function escapeInvalidPageBreaks(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/place-kinds.d.mts

@@ -0,0 +1,18 @@
+/**
+ * Check a district's parent and a route's journeys.
+ *
+ * A district naming no parent is reported at its `subType`; one whose parents
+ * all resolve and none is a settlement or a region is reported at `parents`.
+ * A parent that does not resolve is the Address check's finding, so a district
+ * whose only parents are unresolved earns nothing more here. A route stating no
+ * `data.routes` entry is reported at its `subType`.
+ *
+ * @param {object} note - The note: `file`, `raw` and parsed `fm`.
+ * @param {{index?: object}} [options] - The lint's options.
+ * @returns {object[]} Located findings.
+ */
+export function checkPlaceKind(note: object, { index }?: {
+    index?: object;
+}): object[];
+/** The place kinds a district may stand within. */
+export const DISTRICT_PARENT_KINDS: readonly string[];

package/types/engine/settlement-tables.d.mts

@@ -1,164 +1,31 @@
 /**
- * Every settlements table in a note, read from the raw file so each line
- * number is the file's own.
- *
- * @param {string} raw - The whole note, frontmatter included.
- * @returns {{heading: number, tables: SettlementTable[]}} The `## Settlements`
- *   heading's line, 0 when there is none, and its tables.
- */
-export function findSettlementTables(raw: string): {
-    heading: number;
-    tables: SettlementTable[];
-};
-/**
- * Check a place note's settlements tables.
- *
- * Declared as part of the `place` vocabulary's whole-note check, so the lint
- * runs it with the index every reference resolves through. Without an index
- * nothing is reported.
- *
- * @param {object} note - The note, as the link index hands it over.
- * @param {object} [opts]
- * @param {object} [opts.index] - The link index, holding the whole corpus.
- * @returns {object[]} Findings.
+ * Check indexed rows, locating each finding in its original YAML.
+ * @param {object} note - Indexed note and original locator text.
+ * @param {object} [opts] - Captured context.
+ * @param {object} [opts.index] - Complete local and dependency reference index.
+ * @returns {object[]} Located findings.
  */
 export function checkSettlementTables(note: object, { index }?: {
     index?: object | undefined;
 }): object[];
-/** The heading text a settlements table stands under, at level two. */
-export const SETTLEMENTS_HEADING: "Settlements";
-/**
- * How a region's countryside is held, each the tag a region carries to say so.
- *
- * `holder` is what the `Held by` cell names under that model. `person` says
- * whether that holder may be a person: only where land is held by a person or
- * a house may the cell link a `being`.
- *
- * **The tags stay open.** They are not a declared tag group: a group would
- * report every tag within a typo's distance of one — a region tagged `hellad`
- * reads as a near miss of `held` — and a misspelled model on a note with a
- * table is already reported, because the note then names no model at all.
- *
- * @type {ReadonlyArray<Readonly<{tag: string, holder: string, person: boolean}>>}
- */
-export const HOLDING_MODELS: ReadonlyArray<Readonly<{
-    tag: string;
-    holder: string;
-    person: boolean;
-}>>;
-/**
- * The table's columns, in the order the header states them. An optional
- * column may be left out; the header carries no other column, and keeps this
- * order.
- *
- * @type {ReadonlyArray<Readonly<{name: string, required: boolean}>>}
- */
-export const SETTLEMENT_COLUMNS: ReadonlyArray<Readonly<{
-    name: string;
-    required: boolean;
-}>>;
-/**
- * The rules this module enforces, each `name` the prefix its findings carry.
- *
- * @type {ReadonlyArray<Readonly<{name: string, describe: string}>>}
- */
-export const SETTLEMENT_TABLE_RULES: ReadonlyArray<Readonly<{
-    name: string;
-    describe: string;
-}>>;
 /**
- * One cell, as authored.
- */
-export type Cell = {
-    /**
-     * - The cell, trimmed.
-     */
-    text: string;
-    /**
-     * - The 1-based column its text starts at.
-     */
-    column: number;
-};
-/**
- * One settlements table.
- */
-export type SettlementTable = {
-    /**
-     * - The 1-based line of its header.
-     */
-    line: number;
-    /**
-     * - The header cells.
-     */
-    header: string[];
-    /**
-     * - Whether the header is the declared columns.
-     */
-    wellFormed: boolean;
-    /**
-     * - Each
-     * row's cells keyed by column name; empty when the header is not well formed.
-     */
-    rows: Array<{
-        line: number;
-        cells: Record<string, Cell>;
-    }>;
-    /**
-     * - The 1-based line of its last row.
-     */
-    last: number;
-    /**
-     * - Whether prose follows it before the next heading.
-     */
-    tailed: boolean;
-};
-/**
- * One place note, as the rules read it.
- */
-export type PlaceNode = {
-    /**
-     * - The note.
-     */
-    note: object;
-    /**
-     * - Lower case.
-     */
-    shortcode: string;
-    subType: string;
-    title: string;
-    /**
-     * - Its name and listed forms, lower case.
-     */
-    names: Set<string>;
-    /**
-     * - Enclosing places' shortcodes.
-     */
-    parents: string[];
-    section: {
-        heading: number;
-        tables: SettlementTable[];
-    };
-};
-/**
- * Everything the rules ask of the whole tree.
- */
-export type Corpus = {
-    /**
-     * - By shortcode.
-     */
-    places: Map<string, PlaceNode>;
-    /**
-     * - By note.
-     */
-    byNote: Map<object, PlaceNode>;
-    /**
-     * - Region shortcode → the
-     * settlement notes its table covers.
-     */
-    covers: Map<string, PlaceNode[]>;
-    /**
-     * - Settlement note → the region
-     * notes whose tables link it, in path order.
-     */
-    rowedIn: Map<object, object[]>;
-};
+ * Fail every publishing surface before it writes invalid settlement output.
+ * @param {object[]} records - Indexed records, including documentation projections.
+ * @param {object} opts - Captured context.
+ * @param {(record: object) => string} opts.fileOf - Source filename for a record.
+ * @param {Map<string,object>} [opts.foreignIndex] - Dependency reference targets.
+ * @param {(file: string) => string|undefined} [opts.rawOf] - Captured locator text.
+ * @returns {void}
+ */
+export function assertSettlementRecords(records: object[], { fileOf, foreignIndex, rawOf }?: {
+    fileOf: (record: object) => string;
+    foreignIndex?: Map<string, object> | undefined;
+    rawOf?: ((file: string) => string | undefined) | undefined;
+}): void;
+/**
+ * Render rows once as shared Markdown; all surfaces consume the same table.
+ * @param {object} record - Indexed region.
+ * @returns {string} Generated table and its closing sentence.
+ */
+export function settlementMarkdown(record: object): string;
+export { SETTLEMENTS_HEADING, SETTLEMENT_COLUMNS, SETTLEMENT_ROW_FIELDS, SETTLEMENTS_FIELD, SETTLEMENT_TABLE_RULES } from "./settlement-terms.mjs";

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

@@ -0,0 +1,53 @@
+/** Dependency-free settlement row declarations. @module */
+/** The generated heading. */
+export const SETTLEMENTS_HEADING: "Settlements";
+/** Rendered columns, in their fixed order; Held by and For appear when a row states them. */
+export const SETTLEMENT_COLUMNS: readonly (Readonly<{
+    name: "Name";
+    required: true;
+}> | Readonly<{
+    name: "Market";
+    required: true;
+}> | Readonly<{
+    name: "People";
+    required: true;
+}> | Readonly<{
+    name: "Held by";
+    required: false;
+}> | Readonly<{
+    name: "For";
+    required: false;
+}>)[];
+/** The closed row fields; existing subjects use native Addresses. */
+export const SETTLEMENT_ROW_FIELDS: readonly Readonly<unknown>[];
+/** The place vocabulary's single settlement declaration. */
+export const SETTLEMENTS_FIELD: Readonly<{
+    name: "settlements";
+    kind: "map";
+    shape: "{ rows, tail }";
+    fields: readonly ({
+        name: string;
+        kind: string;
+        required: boolean;
+        shape: string;
+        entries: {
+            kind: string;
+            shape: string;
+            fields: readonly Readonly<unknown>[];
+        };
+        describe: string;
+    } | {
+        name: string;
+        kind: string;
+        required: boolean;
+        shape: string;
+        describe: string;
+        entries?: undefined;
+    })[];
+    describe: "A region's settlement rows and the sentence stating what they leave out; the table is generated from this declaration.";
+}>;
+/** Every semantic finding, named once for the reference and its guards. */
+export const SETTLEMENT_TABLE_RULES: readonly Readonly<{
+    name: string;
+    describe: string;
+}>[];

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";