@heroiclands/package-build 22.4.6 → 22.4.7

package/engine/note-vocabulary.mjs

@@ -85,6 +85,11 @@ import { currentType } from "./ids.mjs";
 // What a place is next to and reachable from — the two relation lists and
 // the checks that hold them to their closed sets and to each other.
 import { checkBorders, checkRoutes } from "./place-relations.mjs";
+import { checkHeld } from "./holdings.mjs";
+// What trade a settlement supports — the scale and the check that holds a
+// value to it, read rather than restated, so the reference below and the
+// finding an author meets state one list.
+import { MARKET_CLASSES, checkMarket } from "./market-class.mjs";
 
 /**
  * One `data:` key a note type may carry.
@@ -141,6 +146,11 @@ import { checkBorders, checkRoutes } from "./place-relations.mjs";
  * @property {readonly DataFieldSpec[]} data - The `data:` keys, closed.
  * @property {readonly string[]|null} [subTypes] - The top-level `subType`
  *   values, as above.
+ * @property {(note: object, opts: {index?: object}) => object[]} [check] - A
+ *   check of the whole note, run by the frontmatter lint beside the field
+ *   checks with the same index. For a rule that is about the note rather than
+ *   one of its fields — a place's tenure is a fact about every affiliation's
+ *   `domains`, and is located at the note's `type:` line.
  */
 
 /* --------------------------------------------------------------------- */
@@ -984,6 +994,7 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     place: Object.freeze({
         subTypes: Object.freeze(["world", "region", "settlement", "site", "structure", "feature"]),
+        check: checkHeld,
         data: Object.freeze([
             {
                 name: "demonym",
@@ -1007,6 +1018,14 @@ export const NOTE_VOCABULARY = Object.freeze({
                 ...NUM,
                 describe: "Approximate population, to two significant digits.",
             },
+            {
+                name: "market",
+                ...NUM,
+                check: checkMarket,
+                describe:
+                    "What trade the settlement supports, on a scale of six: " +
+                    `${MARKET_CLASSES.map((c) => `${c.value} ${c.name}`).join(", ")}.`,
+            },
             {
                 name: "borders",
                 ...LIST,

package/engine/site-build.mjs

@@ -36,7 +36,9 @@
  * `/<package>/<type>-<shortcode>/`. Nothing is generated between them — no
  * section directory, no listing, no `_index.md` but the root's. An index of
  * what the package publishes is a `doc` note carrying a content table, and it
- * is authored where every other page is.
+ * is authored where every other page is. The one file a page carries beside
+ * itself is the map from a place — see `engine/site-maps.mjs` — and a page
+ * that carries one is a leaf bundle at the same address.
  *
  * **Every gate reports; none exits.** The integrity checks a site build needs —
  * a wikilink authored in frontmatter, a name that yields no slug, an unusable
@@ -82,6 +84,8 @@ import {
 import { publishesContentPages } from "../content-config.mjs";
 import { HUGO_CONTENT } from "./site-config.mjs";
 import { homepageLinkTargets, relatedPages } from "./related-pages.mjs";
+import { HOLDINGS_KEYS, foreignHoldingsNodes, holdingsNode, holdingsPages } from "./holdings.mjs";
+import { drawSiteMaps } from "./site-maps.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -489,7 +493,10 @@ export function tableUniverse(pages) {
  * about every other page, known only once the whole tree has resolved — see
  * {@link module:engine/related-pages} — so an authored value is dropped the
  * way `aliases` is, and {@link renderPages} writes the derived block once it
- * holds the graph.
+ * holds the graph. `contains`, `held_by` and `holdings` are dropped for the
+ * same reason — see {@link module:engine/holdings}. **So is `map`**: the
+ * file a place page names is the one the build drew beside it — see
+ * {@link module:engine/site-maps} — and a page with no drawing names none.
  *
  * @param {object} page - The page.
  * @param {object} options
@@ -525,6 +532,8 @@ export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
     if (decorate) decorate(data, page);
     delete data.aliases;
     delete data.related;
+    for (const key of HOLDINGS_KEYS) delete data[key];
+    delete data.map;
     if (webSrc && artSrc) resolveArtFields(data, webSrc, artSrc);
     return data;
 }
@@ -598,11 +607,20 @@ function isPlainObject(value) {
  * `doc` note's `subType` may be spelled the same as another note's `type`, and
  * `doc-gear.md` and `weapongear-gear.md` are distinct.
  *
+ * **A page that carries a file beside itself is a leaf bundle**, `<slug>/index.md`,
+ * because that is the one shape under which Hugo hands a page its own
+ * resources — the map from a place, inlined by the theme through
+ * `.Resources.Get`. The directory is the page, not a section: it holds no
+ * `_index.md`, and the page's stated `url` keeps its address exactly where the
+ * flat file's was.
+ *
  * @param {object} page - The page.
+ * @param {object} [opts]
+ * @param {boolean} [opts.bundle=false] - Whether the page carries a resource.
  * @returns {string} The file, relative to the mount.
  */
-export function pageDestination(page) {
-    return `${page.slug}.md`;
+export function pageDestination(page, { bundle = false } = {}) {
+    return bundle ? `${page.slug}/index.md` : `${page.slug}.md`;
 }
 
 /**
@@ -627,16 +645,25 @@ export function pageDestination(page) {
  * point the resolver answers, and inverted once between them. Nothing is
  * resolved twice.
  *
+ * **A map is written with its page.** The drawing from a place is made before
+ * this render — see {@link module:engine/site-maps} — and handed in keyed by
+ * page URL; the page that owns one is written as a leaf bundle, the file is
+ * copied beside it, and the front matter names it as `map`. Every other page
+ * is written flat, and carries no such key.
+ *
  * @param {object[]} pages - Every page.
  * @param {object} options - Everything the render needs. `homepages` is the
  *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
  *   no part in the render and every part in the graph: a content page links
- *   it by wikilink, and its own markdown links name content pages.
+ *   it by wikilink, and its own markdown links name content pages. `maps` is
+ *   each drawing by the URL of the page that carries it.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[],
- *   related: Map<string, import("./related-pages.mjs").Related>}} `related`
+ *   related: Map<string, import("./related-pages.mjs").Related>,
+ *   maps: number}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
  *   page's, so the caller can write it on the page this render does not.
+ *   `maps` counts the pages written with one.
  */
 export function renderPages(pages, options) {
     const {
@@ -651,6 +678,7 @@ export function renderPages(pages, options) {
         config,
         records = [],
         homepages = [],
+        maps = new Map(),
     } = options;
 
     // The address space the art slots and the body's embeds resolve against:
@@ -783,17 +811,40 @@ export function renderPages(pages, options) {
     }
 
     const related = relatedPages(edges, entries);
+    // What lies within a place, who holds it, and what an affiliation holds
+    // — read off `parents` and `domains` across this package and every
+    // fetched index, local notes first so they shadow a dependency's.
+    const holdings = holdingsPages([
+        ...pages.map((page) => holdingsNode(page.fm, { title: pageTitle(page), url: page.url })),
+        ...foreignHoldingsNodes(foreign?.index),
+    ]);
 
+    let withMap = 0;
     for (const { page, body, data } of rendered) {
         const block = related.get(page.url);
         if (block) data.related = block;
-        const dest = path.join(outRoot, pageDestination(page));
+        Object.assign(data, holdings.get(page.url));
+        const map = maps.get(page.url);
+        const dest = path.join(outRoot, pageDestination(page, { bundle: Boolean(map) }));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
+        if (map) {
+            fs.copyFileSync(map.file, path.join(path.dirname(dest), map.name));
+            data.map = map.name;
+            withMap += 1;
+        }
         fs.writeFileSync(dest, matter.stringify(body, data));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
-    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors, related };
+    return {
+        written: pages.length,
+        byKind,
+        tableErrors,
+        wikiErrors,
+        imageErrors,
+        related,
+        maps: withMap,
+    };
 }
 
 /**
@@ -846,10 +897,15 @@ export function resolveSitePass(name, options) {
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
+ * @param {(engine: string) => string|undefined} [options.locate] - How a
+ *   GraphViz engine's binary is found, for the maps; the real lookup by
+ *   default.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
+ *   wikiErrors: object[], imageErrors: object[], mapFindings: object[],
+ *   manifests: object|null}} `mapFindings` is what drawing the maps found —
+ *   warnings, never a reason to fail the build.
  */
-export function buildSite({ config, sqlTables } = {}) {
+export function buildSite({ config, sqlTables, locate } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
@@ -945,6 +1001,7 @@ export function buildSite({ config, sqlTables } = {}) {
             tableErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            mapFindings: [],
             stats: null,
         };
     }
@@ -963,6 +1020,7 @@ export function buildSite({ config, sqlTables } = {}) {
             tableErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            mapFindings: [],
             stats: {
                 homepages: writeHomepages(homeRoot, homepages, resolved),
                 out: homeRoot,
@@ -1004,6 +1062,7 @@ export function buildSite({ config, sqlTables } = {}) {
             tableErrors: [],
             wikiErrors: [],
             imageErrors: [],
+            mapFindings: [],
         };
     }
 
@@ -1012,6 +1071,22 @@ export function buildSite({ config, sqlTables } = {}) {
         repoRoot: resolved.rootDir,
     });
 
+    // The map from each related place, drawn now that every page is known to
+    // be addressable and before any is written, so the page writer lays each
+    // drawing beside its page. Drawn with `base`, which is what every name
+    // in a drawing links through — the same `<base><slug>/` every other href
+    // composes. Off, nothing is drawn and nothing is asked of GraphViz.
+    const drawn =
+        site.maps ?
+            drawSiteMaps({
+                records: ctx.records,
+                foreignIndex: gates.foreign.index,
+                config: resolved,
+                base,
+                ...(locate ? { locate } : {}),
+            })
+        :   { maps: new Map(), findings: [] };
+
     const rendered = renderPages(pages, {
         outRoot: out,
         sqlTables,
@@ -1021,6 +1096,7 @@ export function buildSite({ config, sqlTables } = {}) {
         foreign: gates.foreign,
         universe: tableUniverse(pages),
         homepages: homepageEntries,
+        maps: drawn.maps,
         pass,
         // What counts as a being is the toolchain's to say, not a consumer's.
         // Asking in a consumer's script is how one came to still be checking
@@ -1053,9 +1129,11 @@ export function buildSite({ config, sqlTables } = {}) {
         tableErrors: rendered.tableErrors,
         wikiErrors: rendered.wikiErrors,
         imageErrors: rendered.imageErrors,
+        mapFindings: drawn.findings,
         stats: {
             ...rendered.byKind,
             homepages: homepagesWritten,
+            maps: rendered.maps,
             out,
         },
     };

package/engine/site-maps.mjs

@@ -0,0 +1,165 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The maps a site build writes into its place pages.
+ *
+ * A place that states, or is named in, a border or a route has a map from it
+ * — the drawing `content-build map --from` makes — and the site build draws
+ * that map for every such place of this package and hands each one to the
+ * page writer, which lays it beside the page as `from-<shortcode>.svg` and
+ * names it in the front matter as `map`. The theme inlines it, so its place
+ * names are links to their pages: every drawing is made with the site's base,
+ * and every `href` in it composes `<base><slug>/` the way every other href
+ * the build renders does.
+ *
+ * GraphViz draws, and a site never fails for want of a map: when the engine is
+ * absent the build says so once, as a warning, and writes every page as it
+ * would without maps. `site.maps: false` says the site carries none and asks
+ * nothing of GraphViz.
+ *
+ * The drawings land under `build/map/site/` — beside the author's own
+ * drawings under `build/map/`, and apart from them, because the site's
+ * carry links and the author's may not — and are copied from there into the
+ * content mount. A build never mutates its inputs.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { buildMaps, relatedPlaces } from "./map-build.mjs";
+import { GRAPHVIZ_INSTALL, findGraphviz } from "./map-graphviz.mjs";
+import { mapWorld } from "./map-places.mjs";
+
+/**
+ * Where the site build draws, below the package root.
+ *
+ * @type {string}
+ */
+export const SITE_MAP_DIR = "build/map/site";
+
+/**
+ * The engine the map from a place is drawn with.
+ *
+ * @type {string}
+ */
+const ENGINE = "neato";
+
+/**
+ * A drawing as the page writer receives it.
+ *
+ * @typedef {object} SiteMap
+ * @property {string} name - The file's name in the page's bundle, and the
+ *   value of the page's `map` key: `from-<shortcode>.svg`.
+ * @property {string} file - Where the drawing is, absolute.
+ */
+
+/**
+ * A GraphViz SVG rewritten for inlining in an HTML page.
+ *
+ * GraphViz writes a standalone document: an XML declaration, a DOCTYPE naming
+ * the SVG 1.1 DTD by URL, generator comments, a root sized in points beside
+ * its `viewBox`, and links through the `xlink` namespace. Inline in HTML the
+ * prologue is invalid, the DTD reference is the one external reference the
+ * drawing would carry, the fixed size fights the column it sits in, and
+ * `xlink:` is the pre-SVG-2 spelling. So the prologue and the comments go,
+ * the root keeps its `viewBox` and loses `width` and `height`, and
+ * `xlink:href` and `xlink:title` become `href` and `title`, with the
+ * namespace declaration they needed.
+ *
+ * @param {string} svg - The SVG as GraphViz wrote it.
+ * @returns {string} The SVG to inline, starting at `<svg`.
+ */
+export function inlineSvg(svg) {
+    const start = svg.indexOf("<svg");
+    let out = start < 0 ? svg : svg.slice(start);
+    out = out.replace(/<!--[\s\S]*?-->\n?/g, "");
+    out = out.replace(/^<svg[^>]*>/, (root) =>
+        root
+            .replace(/\s+(width|height)="[^"]*"/g, "")
+            .replace(/\s+xmlns:xlink="[^"]*"/, "")
+            .replace(/^<svg\s+/, "<svg "),
+    );
+    return out.replace(/\bxlink:(href|title)=/g, "$1=");
+}
+
+/**
+ * Draw the map from every related place of this package.
+ *
+ * @param {object} opts
+ * @param {Array<Record<string, any>>} opts.records - The package's index
+ *   records, as the site build read them.
+ * @param {Map<string, object>} opts.foreignIndex - The fetched indexes the
+ *   site build resolved links against.
+ * @param {object} opts.config - The resolved configuration.
+ * @param {string} opts.base - The site base every page is served under,
+ *   ending in a slash: what every name in a drawing links through.
+ * @param {(engine: string) => string|undefined} [opts.locate] - How the
+ *   engine's binary is found; the real lookup by default.
+ * @returns {{maps: Map<string, SiteMap>, findings: Array<{file: string,
+ *   line?: number, column?: number, severity: "error"|"warning",
+ *   message: string}>}} The drawings, keyed by the URL of the page each
+ *   belongs to, and what the drawing found — one warning naming what to
+ *   install when GraphViz is absent, and a warning for each relation that
+ *   names no place.
+ */
+export function drawSiteMaps({ records, foreignIndex, config, base, locate = findGraphviz }) {
+    /** @type {Map<string, SiteMap>} */
+    const maps = new Map();
+    const outDir = path.join(config.rootDir, ...SITE_MAP_DIR.split("/"));
+    // Every run draws afresh: a place that lost its relations must not keep
+    // the map an earlier run drew.
+    fs.rmSync(outDir, { recursive: true, force: true });
+
+    if (!locate(ENGINE)) {
+        return {
+            maps,
+            findings: [
+                {
+                    file: config.rootDir,
+                    severity: "warning",
+                    message:
+                        `GraphViz's \`${ENGINE}\` is not installed, so no place page carries ` +
+                        `the map from that place; ${GRAPHVIZ_INSTALL} to draw them, or set ` +
+                        "`site.maps: false` to say the site carries none",
+                },
+            ],
+        };
+    }
+
+    const world = mapWorld({
+        records,
+        foreignIndex,
+        contentBase: config.paths.content,
+        base,
+        config,
+    });
+    // This package's related places, which are the ones with a page here to
+    // carry a map. A dependency's place is drawn on those maps and gets none
+    // of its own from this build.
+    const centres = relatedPlaces(world.places).filter((s) => world.places.get(s)?.local);
+    if (centres.length === 0) return { maps, findings: [] };
+
+    const { findings } = buildMaps({ world, outDir, from: centres, locate });
+    for (const centre of centres) {
+        const place = world.places.get(centre);
+        if (!place?.url) continue;
+        const name = `from-${centre}.svg`;
+        const file = path.join(outDir, name);
+        fs.writeFileSync(file, inlineSvg(fs.readFileSync(file, "utf8")));
+        maps.set(place.url, { name, file });
+    }
+    return { maps, findings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.6",
+    "version": "22.4.7",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/holdings.d.mts

@@ -0,0 +1,146 @@
+/**
+ * Read a local note into a node, or `null` for a note that takes no part.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} page - The page it publishes as.
+ * @param {string} page.title - Its published title.
+ * @param {string} page.url - Its URL.
+ * @returns {HoldingsNode|null} The node, or `null` for a note that is neither
+ *   a place nor an affiliation, or that declares no shortcode.
+ */
+export function holdingsNode(fm: object, { title, url }: {
+    title: string;
+    url: string;
+}): HoldingsNode | null;
+/**
+ * Read a fetched index's places and affiliations as nodes.
+ *
+ * An entry carries what the producer's record stated — its name, `subType`,
+ * `parents` and `domains` — and its page URL where the package publishes one.
+ *
+ * @param {Map<string, object>|undefined} foreignIndex - As
+ *   {@link module:engine/metadata-index.loadForeignIndexes} returns it.
+ * @returns {HoldingsNode[]} The nodes, in index order.
+ */
+export function foreignHoldingsNodes(foreignIndex: Map<string, object> | undefined): HoldingsNode[];
+/**
+ * Invert `parents` and `domains` into each page's lists.
+ *
+ * A shortcode is declared once per type: the first node declaring it wins,
+ * so local nodes handed in ahead of fetched ones shadow a dependency's, the
+ * way the link resolver answers. A node with no URL is nobody's entry and
+ * carries no lists of its own, since there is no page to write them on. A
+ * name no node declares is dropped: a `parents` naming nowhere is the map's
+ * finding, a `domains` naming nowhere the reference check's.
+ *
+ * The result holds only pages with at least one entry on at least one list,
+ * and a page's block carries only the keys it has entries for — the theme's
+ * silent-disappear convention, kept at the source.
+ *
+ * @param {Iterable<HoldingsNode|null>} nodes - Every place and affiliation,
+ *   local first. `parents` and `domains` are read as written, so a node
+ *   built by hand may carry them as the note spells them.
+ * @returns {Map<string, Holdings>} URL → the page's lists, sorted.
+ */
+export function holdingsPages(nodes: Iterable<HoldingsNode | null>): Map<string, Holdings>;
+/**
+ * Check a place note's tenure: a settlement, a site or a structure that no
+ * affiliation's `domains` names is unheld land, reported as a warning at the
+ * note's `type:` line.
+ *
+ * Declared on the `place` vocabulary as its type-level check, so the lint
+ * runs it beside the field checks with the same index. Without an index the
+ * question cannot be asked and 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 every affiliation.
+ * @returns {object[]} Findings.
+ */
+export function checkHeld(note: object, { index }?: {
+    index?: object | undefined;
+}): object[];
+/**
+ * The keys this module writes, and which a note cannot author: `contains`
+ * and `held_by` on a place, `holdings` on an affiliation.
+ *
+ * @type {readonly string[]}
+ */
+export const HOLDINGS_KEYS: readonly string[];
+/**
+ * The place subTypes tenure is checked on. A region is held through its
+ * polity's `domains`, a world by nobody, a feature by nobody — a river has no
+ * lord — so the rest are the kinds of place a body holds directly.
+ *
+ * @type {readonly string[]}
+ */
+export const HELD_SUBTYPES: readonly string[];
+/**
+ * One entry of a holdings list — a page a reader is pointed at.
+ */
+export type HoldingsEntry = {
+    /**
+     * The page's published title.
+     */
+    title: string;
+    /**
+     * `<base><slug>/` — the page's address as every
+     * href this build renders composes it.
+     */
+    url: string;
+    /**
+     * The note's `type` — `place` or `affiliation`.
+     */
+    type: string;
+    /**
+     * The note's `subType`, where it declares one.
+     */
+    subType?: string | undefined;
+};
+/**
+ * One place or affiliation, as the derivation reads it — a local page or a
+ * fetched index entry through one shape.
+ */
+export type HoldingsNode = {
+    /**
+     * Lower case.
+     */
+    shortcode: string;
+    type: "place" | "affiliation";
+    subType?: string | undefined;
+    /**
+     * The page's published title.
+     */
+    title: string;
+    /**
+     * The page's URL; absent where the package
+     *      publishes no page for it.
+     */
+    url?: string | undefined;
+    /**
+     * What a place sits within, as written.
+     */
+    parents: string[];
+    /**
+     * What an affiliation holds, as written.
+     */
+    domains: string[];
+};
+/**
+ * The lists one page carries. Every key is optional, and a key present holds
+ * at least one entry.
+ */
+export type Holdings = {
+    /**
+     * Places whose `parents` name this one.
+     */
+    contains?: HoldingsEntry[] | undefined;
+    /**
+     * Affiliations whose `domains` name this one.
+     */
+    held_by?: HoldingsEntry[] | undefined;
+    /**
+     * Places this affiliation's `domains` name.
+     */
+    holdings?: HoldingsEntry[] | undefined;
+};

package/types/engine/index.d.mts

@@ -16,11 +16,14 @@ export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
 export * as placeRelations from "./place-relations.mjs";
+export * as holdings from "./holdings.mjs";
+export * as marketClass from "./market-class.mjs";
 export * as mapPlaces from "./map-places.mjs";
 export * as mapLayout from "./map-layout.mjs";
 export * as mapDot from "./map-dot.mjs";
 export * as mapGraphviz from "./map-graphviz.mjs";
 export * as mapBuild from "./map-build.mjs";
+export * as siteMaps from "./site-maps.mjs";
 export * as systems from "./systems.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";

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

@@ -21,7 +21,7 @@ export function findGraphviz(engine: string, { env, fallbacks }?: {
 }): string | undefined;
 /**
  * What to say when an engine is not installed: the name, and what installs
- * it on the two platforms a contributor is likely to be on.
+ * it.
  *
  * @param {string} engine - The engine that was wanted.
  * @returns {string} The message.
@@ -59,3 +59,10 @@ export function renderDot(dotPath: string, outPath: string, { binary, format, ar
  * @type {readonly string[]}
  */
 export const GRAPHVIZ_ENGINES: readonly string[];
+/**
+ * What installs GraphViz on the two platforms a contributor is likely to be
+ * on, as the clause every "not installed" message ends with.
+ *
+ * @type {string}
+ */
+export const GRAPHVIZ_INSTALL: string;

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

@@ -34,6 +34,32 @@ export function loadMapWorld({ config, contentBase, base, problems }: {
     base?: string | undefined;
     problems?: object[] | undefined;
 }): MapWorld;
+/**
+ * The world a map is drawn from, out of records and indexes a caller already
+ * holds: this package's places from its index records, and every
+ * dependency's from the fetched indexes. The site build reads its corpus and
+ * its foreign indexes once for every surface it publishes, and hands them
+ * here rather than walking the tree a second time.
+ *
+ * @param {object} opts
+ * @param {Array<Record<string, any>>} opts.records - Index records, as
+ *   {@link module:engine/content-index.indexRecordsFor} returns them.
+ * @param {Map<string, object>} opts.foreignIndex - The fetched indexes, as
+ *   {@link module:engine/metadata-index.loadForeignIndexes} returns `index`.
+ * @param {string} opts.contentBase - The content root the records were read from.
+ * @param {string} [opts.base] - The site base this package's pages are served
+ *   under. Absent, no local place carries a URL.
+ * @param {object} opts.config - The resolved configuration.
+ * @returns {MapWorld} The world, with nothing stale: the caller has already
+ *   judged its indexes usable.
+ */
+export function mapWorld({ records, foreignIndex, contentBase, base, config }: {
+    records: Array<Record<string, any>>;
+    foreignIndex: Map<string, object>;
+    contentBase: string;
+    base?: string | undefined;
+    config: object;
+}): MapWorld;
 /**
  * Analyse the containment tree.
  *