@heroiclands/package-build 23.12.8 → 24.0.0

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

@@ -3,7 +3,7 @@
  *
  * `[{name, url, children?: [{name, url}]}]`, every `url` absolute. Checked
  * on fetch and again on read: a file that is not a navigation would otherwise
- * reach the generated menu as `undefined` labels and links.
+ * reach the menu as `undefined` labels and links.
  *
  * @param {unknown} value - The parsed document.
  * @param {string} where - What is being checked, for the error.
@@ -11,18 +11,6 @@
  * @throws {TypeError} When the shape is not a navigation.
  */
 export function checkNavigation(value: unknown, where?: string): NavigationEntry[];
-/**
- * The `[[menu.main]]` entries a navigation renders as.
- *
- * Entry for entry, in order; a dropdown is an entry with an `identifier` and
- * its children are entries naming it as `parent`, which is how the theme's
- * header partial draws one. Weights count from one within each level, so the
- * order is the navigation's and not Hugo's alphabetical fallback.
- *
- * @param {readonly NavigationEntry[]} navigation - The navigation.
- * @returns {MenuEntry[]} The menu entries.
- */
-export function menuEntries(navigation: readonly NavigationEntry[]): MenuEntry[];
 /**
  * Where the fetched navigation sits.
  *
@@ -64,137 +52,45 @@ export function fetchNavigation(config: object, { url, fetch }?: {
     fetch?: typeof globalThis.fetch | undefined;
 }): Promise<string>;
 /**
- * The `themesDir` for a repository, as the path from `build/hugo/` to the
- * directory holding the theme.
- *
- * The theme ships inside this package at `hugo-theme/`, so the directory Hugo
- * reads themes from is {@link PACKAGE_ROOT}. `theme` stays {@link THEME}, so
- * Hugo opens `<themesDir>/hugo-theme/layouts`.
- *
- * Written as a path rather than assumed: `build/hugo/` and the installed
- * package sit at whatever distance the install put them, and a worktree
- * resolving its parent's install says so in the generated file.
- *
- * @param {string} rootDir - The repository root.
- * @returns {string} The relative path, POSIX-separated.
- */
-export function resolveThemesDir(rootDir: string): string;
-/**
- * The Hugo configuration, as an object.
- *
- * Pure: every input is handed in, so a test can describe the generated shape
- * without a repository on disk. {@link generateHugoConfig} is the same function
- * with the reading put back.
+ * What a site is, read from the configuration: its address, its title and the
+ * parameters its layouts read.
  *
  * `checkHomepage` runs first, before any value is composed — a missing or
  * mismatched `package.json` `homepage` is a finding on every site build.
  *
  * @param {object} options - The sources.
  * @param {object} options.config - The resolved build configuration.
- * @param {readonly NavigationEntry[]} options.navigation - The navigation.
- * @param {string} options.themesDir - From {@link resolveThemesDir}.
- * @returns {Record<string, any>} The configuration Hugo reads.
+ * @returns {{baseURL: string, title: string, params: Record<string, unknown>}}
+ *   The site. `params` holds `description`, `author`, `cdnBaseURL`, `brand`,
+ *   `notfound` and `scriptFonts`, each where the configuration states it.
  * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
  *   configuration declares no `site.title` or `packageBuild.manifest.title`, no
  *   `site.description`, or no `site.assets`.
  */
-export function hugoConfig({ config, navigation, themesDir }: {
+export function siteSettings({ config }: {
     config: object;
-    navigation: readonly NavigationEntry[];
-    themesDir: string;
-}): Record<string, any>;
-/**
- * The configuration as the TOML Hugo reads.
- *
- * @param {Record<string, unknown>} generated - From {@link hugoConfig}.
- * @returns {string} The file's contents.
- */
-export function hugoToml(generated: Record<string, unknown>): string;
-/**
- * The Hugo configuration, every source read from the repository.
- *
- * Reads the cached navigation and the installed theme's location, and
- * composes them with {@link hugoConfig}. Nothing is written, so a caller can
- * run this before touching the output tree and fail with it intact.
- *
- * @param {object} config - The resolved build configuration.
- * @returns {Record<string, any>} The configuration Hugo reads.
- * @throws {Error} When any source is missing or wrong.
- */
-export function generateHugoConfig(config: object): Record<string, any>;
-/**
- * Write `build/hugo/hugo.toml`.
- *
- * @param {object} config - The resolved build configuration.
- * @param {Record<string, unknown>} [generated] - The configuration to write,
- *   when the caller already generated it. Generated here otherwise.
- * @returns {{file: string}} The file written.
- */
-export function writeHugoConfig(config: object, generated?: Record<string, unknown>): {
-    file: string;
+}): {
+    baseURL: string;
+    title: string;
+    params: Record<string, unknown>;
 };
-/** The Hugo source directory, relative to the repository root. */
-export const HUGO_SOURCE: "build/hugo";
-/** The content mount `package-build site` writes, relative to the repository root. */
-export const HUGO_CONTENT: "build/hugo/content";
 /**
  * The directory that is deployed, relative to the repository root.
  *
- * Hugo renders into `<DEPLOY_ROOT>/<contentPackage>/`; `package-build
- * site-root` writes `_headers` beside it and the search index inside it.
+ * `package-build site build` renders into `<DEPLOY_ROOT>/<contentPackage>/`
+ * and writes `_headers` beside it and the search index inside it.
  */
 export const DEPLOY_ROOT: "build/site";
-/** The theme's directory name under `themesDir`. */
-export const THEME: "hugo-theme";
-/** The locale every site renders in. */
-export const LOCALE: "en-us";
 /**
  * The brand chrome's own links, the same on every site.
  *
- * `logo` is resolved through the theme's `cdn-url.html`, so it is a path on
- * the asset host rather than an address.
+ * `logo` is a path on the asset host rather than an address.
  */
 export const BRAND: Readonly<{
     logo: "images/brand/sohl-icon-white.webp";
     licenseURL: "https://www.heroiclands.org/license/";
     discordURL: "https://discord.gg/EwMfkNd3az";
 }>;
-/**
- * The kinds no site renders.
- *
- * A site is its homepage and its pages: `home` and `page` are the only kinds,
- * for every package and whatever its notes carry. A `section` is a listing
- * Hugo would generate from a content directory; `taxonomy` and `term` are
- * listings it would generate from `tags:`; `RSS` is a feed. Every structure
- * between the homepage and the pages is authored instead, as a `doc` note
- * carrying a content table — a tag is a field such a table filters on, not a
- * page of its own.
- */
-export const DISABLE_KINDS: readonly string[];
-/**
- * The markup settings the toolchain's own output requires.
- *
- * Pages are written with raw HTML in them — a `<figure>` for every image, a
- * `<span>` marking an unresolved link — and Goldmark drops raw HTML unless
- * told otherwise. A theme cannot supply this: Hugo does not merge a theme's
- * `markup` block.
- *
- * `extensions.taskList` is off because the format has no checkbox: Goldmark
- * enables it by default, which is the only reason a list item opened with
- * `[ ]` renders a `<input type="checkbox">` here and the same two characters as
- * plain text in the pack and the book. Off, a list item's text begins right
- * after its marker on every surface.
- */
-export const MARKUP: Readonly<{
-    goldmark: Readonly<{
-        renderer: Readonly<{
-            unsafe: true;
-        }>;
-        extensions: Readonly<{
-            taskList: false;
-        }>;
-    }>;
-}>;
 /** Where the navigation is published. */
 export const NAVIGATION_URL: "https://www.heroiclands.org/nav.json";
 /** The cached navigation's file name. */
@@ -216,19 +112,3 @@ export type NavigationEntry = {
      */
     children?: NavigationEntry[] | undefined;
 };
-/**
- * A Hugo menu entry, as `[[menu.main]]` states one.
- */
-export type MenuEntry = {
-    name: string;
-    url: string;
-    weight: number;
-    /**
-     * - Set on an entry that has children.
-     */
-    identifier?: string | undefined;
-    /**
-     * - Set on a child, naming its parent's identifier.
-     */
-    parent?: string | undefined;
-};

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

@@ -0,0 +1,73 @@
+/**
+ * Text escaped for XML content and attribute values.
+ *
+ * @param {unknown} value - The text.
+ * @returns {string} The escaped text.
+ */
+export function escapeXml(value: unknown): string;
+/**
+ * A date as an RFC 3339 timestamp, or `""` for a value that is no date.
+ *
+ * @param {unknown} value - A date, or a string a `Date` reads.
+ * @returns {string} The timestamp, in UTC.
+ */
+export function timestamp(value: unknown): string;
+/**
+ * A site's sitemap.
+ *
+ * @param {Array<{loc: string, lastmod?: unknown}>} entries - Each page's full
+ *   address, and the date it states where it states one.
+ * @returns {string} The document.
+ */
+export function sitemapXml(entries: Array<{
+    loc: string;
+    lastmod?: unknown;
+}>): string;
+/**
+ * A sitemap index naming other sitemaps.
+ *
+ * @param {readonly string[]} sitemaps - Each sitemap's full address.
+ * @returns {string} The document.
+ */
+export function sitemapIndexXml(sitemaps: readonly string[]): string;
+/**
+ * The `robots.txt` of a site's root: every agent may read every page, and
+ * every sitemap is named.
+ *
+ * @param {readonly string[]} sitemaps - Each sitemap's full address, the
+ *   sitemap index first.
+ * @returns {string} The file.
+ */
+export function robotsTxt(sitemaps: readonly string[]): string;
+/**
+ * An Atom feed.
+ *
+ * The feed is dated by its newest entry, and an entry by its own date, so the
+ * feed changes only when a post does.
+ *
+ * @param {object} feed - The feed.
+ * @param {string} feed.title - The feed's title.
+ * @param {string} feed.id - The full address of the page the feed follows,
+ *   which is also its id.
+ * @param {string} feed.self - The feed's own full address.
+ * @param {string} [feed.author] - Who writes the posts, where an entry names
+ *   no author of its own.
+ * @param {Array<{title: string, url: string, date: unknown, author?: string,
+ *   summary?: string, content?: string}>} feed.entries - The posts, each with
+ *   its full address and its HTML `content`.
+ * @returns {string} The document.
+ */
+export function atomFeed({ title, id, self, author, entries }: {
+    title: string;
+    id: string;
+    self: string;
+    author?: string | undefined;
+    entries: Array<{
+        title: string;
+        url: string;
+        date: unknown;
+        author?: string;
+        summary?: string;
+        content?: string;
+    }>;
+}): string;

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

@@ -2,7 +2,9 @@
  * Build the address index a site's wikilink resolver reads.
  *
  * @param {readonly SiteEntry[]} entries - Every page the site will publish,
- *   each already knowing its own `url`.
+ *   each already knowing its own `url`. An entry may carry the `anchors` its
+ *   body declares, from a content-index record, in place of the body they are
+ *   read from.
  * @param {object} [options] - Cross-package inputs.
  * @param {string} [options.package] - The builder's own content package.
  * @param {string} [options.currentDate="720.1"] - Setting-wide neutral date for recurring events.
@@ -156,11 +158,11 @@ export type SiteEntry = {
     /**
      * URL segment.
      */
-    slug: string;
+    slug?: string | undefined;
     /**
      * Source file's basename, e.g. `Climbing.md`.
      */
-    base: string;
+    base?: string | undefined;
     /**
      * The page's published address.
      */
@@ -171,6 +173,12 @@ export type SiteEntry = {
      *  page is indexed as declaring none.
      */
     body?: string | undefined;
+    /**
+     * The anchors the body declares, when the
+     * caller holds them already — a content-index
+     * record's — in place of reading `body`.
+     */
+    anchors?: object[] | undefined;
 };
 /**
  * The resolved index and everything a wikilink resolver reads beside it.

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

@@ -1,14 +1,24 @@
 /**
- * Render one complete buffer with no configuration, index, filesystem or database.
+ * Render one complete buffer.
+ *
+ * Without `index` the buffer is rendered with no configuration, content index,
+ * filesystem or database: wikilinks, spans and expressions show as highlighted
+ * authored source. With `index` the buffer is expanded as the website expands
+ * a page and rendered as every target renders it, so links, embeds, marked
+ * text, icons and figure numbers read as they will on the page; only what a
+ * buffer cannot answer, such as a query, stays highlighted source.
+ *
  * @param {string} text - Markdown, optionally beginning with YAML frontmatter.
- * @param {{dark?: boolean, infobox?: boolean, file?: string, currentDate?: string}} [options] - Explicit palette, profile visibility, diagnostic filename and neutral current date (default "720.1").
+ * @param {{dark?: boolean, infobox?: boolean, file?: string, currentDate?: string,
+ *   index?: import("./preview-index.mjs").PreviewIndex}} [options] - Explicit palette, profile visibility, diagnostic filename, neutral current date (default "720.1") and the content index, from {@link module:engine/preview-index.previewIndex}.
  * @returns {{ok: boolean, html: string, frontmatter: object, findings: object[]}} HTML and metadata with locally calculable ages; unavailable ages remain absent or null.
  */
-export function renderPreview(text: string, { dark, infobox, file, currentDate }?: {
+export function renderPreview(text: string, { dark, infobox, file, currentDate, index }?: {
     dark?: boolean;
     infobox?: boolean;
     file?: string;
     currentDate?: string;
+    index?: import("./preview-index.mjs").PreviewIndex;
 }): {
     ok: boolean;
     html: string;
@@ -23,19 +33,5 @@ export function renderPreview(text: string, { dark, infobox, file, currentDate }
 export function readPreviewCurrentDate(root: string): Promise<string>;
 /** Both explicit palettes, scoped to the preview container. */
 export function previewStyles(): string;
-/** Explicit dependency policy: a new registered helper requires a preview decision. */
-export const PREVIEW_HELPERS: Readonly<{
-    eq: "local";
-    gt: "local";
-    gte: "local";
-    lt: "local";
-    lte: "local";
-    not: "local";
-    and: "local";
-    or: "local";
-    words: "local";
-    digits: "local";
-    sql: "dependent";
-    dateformat: "dependent";
-    ref: "reference";
-}>;
+export { PREVIEW_HELPERS };
+import { PREVIEW_HELPERS } from "./preview-source.mjs";

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

@@ -0,0 +1,171 @@
+/**
+ * Pages in the order a reader walks them: by `weight`, lightest first and an
+ * unweighted page last; then newest first by `date`; then by title; then by
+ * address. A page's own `weight` and `date` are read before its `params`'.
+ *
+ * @template {{title?: string, url: string, date?: unknown, weight?: number, params?: object}} T
+ * @param {readonly T[]} pages - The pages.
+ * @returns {T[]} A sorted copy.
+ */
+export function siteOrder<T extends {
+    title?: string;
+    url: string;
+    date?: unknown;
+    weight?: number;
+    params?: object;
+}>(pages: readonly T[]): T[];
+/**
+ * Every page of a site: the pages it is given, with their siblings, and the
+ * listings derived from them.
+ *
+ * @param {object} site - The site, as {@link writeSite} takes it.
+ * @param {readonly object[]} pages - The home page, the regular pages and any
+ *   authored section pages.
+ * @returns {object[]} Every page, home first, then the regular pages, the
+ *   sections, and the tag pages.
+ */
+export function siteTree(site: object, pages: readonly object[]): object[];
+/**
+ * Write the files the layouts link: the theme's own, and the code stylesheet.
+ *
+ * @param {string} out - The directory the site is written to.
+ * @param {string} [staticDir] - The theme's own files.
+ * @returns {string[]} The files the theme generates, each written. The theme's
+ *   own files are copied as a tree and not listed.
+ */
+export function writeThemeFiles(out: string, staticDir?: string): string[];
+/**
+ * Draw a site and write it.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.site - The site, as
+ *   {@link module:engine/site-theme.createSiteTheme} takes it, with `tagPages`,
+ *   `feed` and `sitemaps` as the module description sets out. `pages` and
+ *   `pageExists` are filled in here.
+ * @param {readonly object[]} options.pages - The home page, the regular pages
+ *   and any authored section pages, each as a layout is given it.
+ * @param {string} options.out - The directory written to. Emptied first.
+ * @param {(finding: import("./site-theme.mjs").Finding) => void} [options.report] -
+ *   Receives each finding the layouts make.
+ * @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.
+ * @returns {{files: string[], pages: string[], findings: object[]}} Every file
+ *   written, the address of every page, 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 }: {
+    site: object;
+    pages: readonly object[];
+    out: string;
+    report?: ((finding: import("./site-theme.mjs").Finding) => void) | undefined;
+    staticDir?: string | undefined;
+    only?: ReadonlySet<string> | undefined;
+}): {
+    files: string[];
+    pages: string[];
+    findings: object[];
+};
+/**
+ * A package's pages, from its site build.
+ *
+ * Each body is rendered by the `web` renderer from the markdown the build
+ * expanded, and each page carries what it tells the search; see
+ * {@link module:engine/site-search}. The site carries what the configuration
+ * asks for: `site.tags` as `tagPages`, `site.feed` as the feed's section, each
+ * package of `site.sitemaps` as its sitemap's address on the site's origin,
+ * and each of `site.mergeIndexes` as the path of its search bundle.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {object} options.built - What `buildSite` returned with `write: false`.
+ * @param {{baseURL: string, title: string, params: object}} options.settings -
+ *   From {@link module:engine/site-config.siteSettings}.
+ * @param {readonly {name: string, url: string, children?: object[]}[]} [options.navigation] -
+ *   The menu.
+ * @param {number} [options.year] - The year the footer states.
+ * @returns {{site: object, pages: object[], pageOf: (entry: object) => object}}
+ *   What {@link writeSite} is given, and how one note the build rendered again
+ *   becomes its page.
+ */
+export function packageSite({ config, built, settings, navigation, year }: {
+    config: object;
+    built: object;
+    settings: {
+        baseURL: string;
+        title: string;
+        params: object;
+    };
+    navigation?: readonly {
+        name: string;
+        url: string;
+        children?: object[];
+    }[] | undefined;
+    year?: number | undefined;
+}): {
+    site: object;
+    pages: object[];
+    pageOf: (entry: object) => object;
+};
+/**
+ * The directory a package's site is written to: its base path under the
+ * deployed root, so a site served at `/` is written at the root itself.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {string} root - The deployed root.
+ * @returns {string} The directory.
+ */
+export function siteDirectory(config: object, root: string): string;
+/**
+ * Copy the script fonts the site's pages set their marked text in.
+ *
+ * @param {object} config - The resolved configuration.
+ * @param {string} out - The directory the site is written to.
+ * @returns {{findings: object[], count: number, dest?: string}} What checking
+ *   the installed fonts found, and how many files were copied where. Nothing is
+ *   copied when there is a finding, or when the package sets no script.
+ */
+export function deliverSiteFonts(config: object, out: string): {
+    findings: object[];
+    count: number;
+    dest?: string;
+};
+/**
+ * Build a package's site from its content tree and write it.
+ *
+ * The site's address, title and menu are read before the tree is, so a site
+ * that cannot be described fails before anything is built. A gate that fires
+ * stops the build before anything is written; a note in error is written as
+ * its page shows it, with the finding in what is returned, which
+ * `siteBuildFailed` reads.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @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.
+ * @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
+ *   written, the pages it was written from and how a note rendered again
+ *   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 }: {
+    config: object;
+    out: string;
+    year?: number | undefined;
+}): Promise<{
+    built: object;
+    written: object | null;
+    fonts: object | null;
+    site?: object;
+    pages?: object[];
+    pageOf?: (entry: object) => object;
+}>;
+/**
+ * The files the layouts link that the theme ships as they are: the site and
+ * icon stylesheets, the spoiler script, the icon font and the theme's images.
+ */
+export const SITE_STATIC_DIR: string;

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

@@ -27,12 +27,16 @@ export function noindexHeaders(): string[];
  * 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 {string} [options.pkg] - The content package, whose site is served at
+ *   `/<pkg>/` unless `base` says otherwise.
+ * @param {string} [options.base] - The path the site is served at, beginning
+ *   and ending with `/`.
  * @param {boolean} [options.fonts] - Whether the site carries the fonts.
  * @returns {string} The file's contents.
  */
-export function headers({ pkg, fonts }?: {
+export function headers({ pkg, base, fonts }?: {
     pkg?: string | undefined;
+    base?: string | undefined;
     fonts?: boolean | undefined;
 }): string;
 export function indexSite(where: {
@@ -59,7 +63,10 @@ export function indexSite(where: {
  *
  * @param {object} options - Options.
  * @param {string} options.pkg - The content package name, which is also the
- *   directory Hugo rendered into.
+ *   directory the site is rendered into unless `base` says otherwise.
+ * @param {string} [options.base] - The path the site is served at, beginning
+ *   and ending with `/`; the site is rendered into that path under `out`, so
+ *   a site served at `/` is rendered at `out` itself.
  * @param {string} options.out - The directory that is deployed.
  * @param {boolean} [options.search] - Whether to build the search index;
  *   `site.search` in the configuration. Default `true`.
@@ -73,8 +80,9 @@ export function indexSite(where: {
  *   under the prefix; or, located at the rendered site, when the indexer
  *   fails.
  */
-export function writeSiteRoot({ pkg, out, search, indexer }: {
+export function writeSiteRoot({ pkg, base, out, search, indexer }: {
     pkg: string;
+    base?: string | undefined;
     out: string;
     search?: boolean | undefined;
     indexer?: SiteIndexer | undefined;

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

@@ -0,0 +1,54 @@
+/**
+ * The continents and regions every place lies in.
+ *
+ * @param {Map<string, {shortcode: string, name: string, subType?: string, parents: string[]}>} places -
+ *   Every place, by shortcode, as {@link module:engine/map-places.mapWorld} reads them.
+ * @returns {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}}
+ *   The names of the continents and the outermost regions the given places lie
+ *   in, each sorted.
+ */
+export function placeGeography(places: Map<string, {
+    shortcode: string;
+    name: string;
+    subType?: string;
+    parents: string[];
+}>): (shortcodes: Iterable<string>) => {
+    continents: string[];
+    regions: string[];
+};
+/**
+ * The places a note lies in: itself for a place, its `homes` and its
+ * `locations` otherwise.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @returns {string[]} Shortcodes, lower case.
+ */
+export function notePlaces(fm: object): string[];
+/**
+ * What a note's page tells the search.
+ *
+ * @param {object} fm - The page's frontmatter: the note's, with its `package`.
+ * @param {object} options - What the values resolve against.
+ * @param {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}} options.geography -
+ *   From {@link placeGeography}.
+ * @param {object} [options.index] - The site's address index, which names the
+ *   culture `data.culture` names.
+ * @returns {{filters: Array<{name: string, values: string[]}>, names: string[]}}
+ *   Each filter with a value, in {@link SEARCH_FILTERS} order, and the names a
+ *   search weights.
+ */
+export function searchMetadata(fm: object, { geography, index }: {
+    geography: (shortcodes: Iterable<string>) => {
+        continents: string[];
+        regions: string[];
+    };
+    index?: object | undefined;
+}): {
+    filters: Array<{
+        name: string;
+        values: string[];
+    }>;
+    names: string[];
+};
+/** The filters a note's page carries, in the order a reader is offered them. */
+export const SEARCH_FILTERS: readonly string[];

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

@@ -0,0 +1,44 @@
+/**
+ * Serve a package's site, and keep it current.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {string} options.out - The site's directory under the deployed
+ *   root, which the site is written to.
+ * @param {string} [options.root] - The deployed root, which is served. The
+ *   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
+ *   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,
+ *   `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.
+ */
+export function serveSite({ config, out, root, host, port, search, year, report, }: {
+    config: object;
+    out: string;
+    root?: string | undefined;
+    host?: string | undefined;
+    port?: number | undefined;
+    search?: boolean | undefined;
+    year?: number | undefined;
+    report?: ((event: {
+        kind: string;
+        built?: object;
+        files?: string[];
+        findings?: object[];
+        error?: unknown;
+    }) => void) | undefined;
+}): Promise<{
+    url: string;
+    close: () => Promise<void>;
+    settled: () => Promise<void>;
+}>;
+/** The address a served page listens on for the server's reloads. */
+export const RELOAD_PATH: "/__package-build/reload";