@heroiclands/package-build 22.4.4 → 22.4.6

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @heroiclands/package-build
 
+## 22.4.6
+
+### Patch Changes
+
+`content-build map --chart <shortcode>` draws the chart from a place: the map from it at a larger horizon, north up, the hops chaining on as long as none turns back, each place on the ring of its summed days and each hop beyond the neighbours drawn fainter. `--horizon <days>` sets how far the rings reach, a year by default, and a place farther than that is left out.
+
+## 22.4.5
+
+### Patch Changes
+
+A `place` note may state what it is next to and what it is reachable from, as `data.borders` (`{ to, bearing }`) and `data.routes` (`{ to, bearing, mode, days, terrain?, leagues? }`), with bearings from the eight compass points, modes `land | boat | ship`, days from the marker scale `1 2 3 5 10 20 30 45 60 90 180 360` and terrains from a closed registry. `content-build lint` checks that every `to` is a place, that every value is from its set, and that the other note states the pair back — a missing reciprocal is a warning naming both notes, a contradictory one an error. The content index carries both lists, so a dependency's places take part.
+
+**Maps**
+
+- A new `content-build map --tree` draws the containment tree from `parents`, clustered by continent, and reports a place with no parent, a parent no place declares, and a cycle.
+- `content-build map --from <shortcode>` draws the map from that place: north up, each neighbour at its bearing and on a ring of its days, places two hops out drawn dimmer.
+- `--from all` draws one map for every place with a border or a route, and `--travel` draws the whole route graph.
+- The drawings land under `build/map/` as SVG beside their DOT source; GraphViz is needed for this command alone, and its absence is reported plainly.
+
+**Site**
+
+- The rendered site carries a search index, built beside the pages when the site's root files are written and served with them.
+- `site.search: false` in `package-build.config.yaml` turns it off.
+
 ## 22.4.4
 
 ### Patch Changes

package/CONTENT.md

@@ -1168,8 +1168,35 @@ builder, so schema and compiler cannot disagree. The hand-written compilers —
 `being`, `macro`, `doc` and the three map types — declare theirs in
 `sohl/note-schemas.mjs`.
 
+**A place's `borders` and `routes` are checked from both ends.** A `place`
+note states what it is next to and what it is reachable from as two `data:`
+lists — `borders: [{ to, bearing }]` and
+`routes: [{ to, bearing, mode, days, terrain?, leagues? }]` — and every value
+is from a closed set: the eight bearings, `land | boat | ship`, a days scale of
+`1 2 3 5 10 20 30 45 60 90 180 360`, and a terrain registry in which each
+terrain names the modes that cross it. Every `to` must be the shortcode of a
+place, here or in a fetched index. The other end must state the pair back —
+at the opposite bearing, and for a route by the same mode in the same days.
+A neighbour stating nothing is a warning naming both notes; one stating a
+different bearing, mode or days is an error, as is a border to the note's own
+parent or child, or a pair listed twice by one mode. Each finding lands on the
+entry that states it. The keys, the sets and the days scale are specified under
+`type: place` in `docs/content-format.md`.
+
 Nothing here writes. A check reports and an author fixes.
 
+**`content-build map` draws what those keys state.** `--tree` is the author's
+check of `parents` — the containment tree, clustered by continent, with a
+place no parent reaches, a parent no place declares and a cycle flagged red
+and reported as findings. `--from <shortcode>` is the reader's map: the place
+at the centre, north up, each neighbour at the angle of its bearing and on a
+log-spaced ring of its days, a second hop drawn dimmer where the two hops
+agree; `--from all` draws one for every place with a relation. `--travel` is
+the whole route graph. Every drawing reads the content index, so a
+dependency's places take part, and lands under `build/map/` as a `.dot`
+beside its `.svg`; GraphViz draws, and is needed by this command alone. The
+command and its rings are documented in `docs/commands.md`.
+
 ### The `data:` container is closed; the top level is not
 
 A note's frontmatter has three regions, and only one of them is open:
@@ -1409,7 +1436,9 @@ mount's `_index.md` as the `home` kind at `baseURL`, which is
 since Cloudflare Pages would apply it. Its `_headers` suppress indexing on
 every host-assigned address and nothing else: no `Cache-Control` is pinned on
 the prefix root, because a lifetime on the homepage would hold a stale copy at
-the most-linked address after a deploy.
+the most-linked address after a deploy. The same command then indexes the
+rendered pages for search into `<package>/pagefind/`, served with the rest of
+the site; `site.search: false` skips it.
 
 ### The homepage's own links
 

package/README.md

@@ -335,6 +335,7 @@ npx package-build lang coverage [--unused]
 npx package-build lang hardcoded
 npx package-build bundle check
 npx package-build release [--no-pdf]
+npx package-build site-root [--out <dir>]
 npx package-build deploy <stage>
 npx package-build container <stage> <start|stop|restart|recreate|rm|status|logs|pull>
 npx package-build e2e <seed|run|open|fast|sweep>
@@ -345,6 +346,14 @@ npx package-build e2e <seed|run|open|fast|sweep>
 publishes a content tree — the book that tree compiles to, as
 `<artifact>-<version>.pdf`.
 
+`package-build site-root` finishes a site build. Hugo renders into
+`build/site/<contentPackage>/`; this writes the deployment's `_headers` beside
+that, and indexes the rendered pages for search with Pagefind into
+`build/site/<contentPackage>/pagefind/`, deployed with the pages and served at
+`/<contentPackage>/pagefind/`. The dependency is this package's, declared once,
+so every site — and every local build — gets an index without the repository
+adding one; `site.search: false` in `package-build.config.yaml` turns it off.
+
 The book is **built by default and never fatal**. A package publishing only a
 homepage, one with no `pdf:` block, and one with no content tree each build
 none and say so; `--no-pdf` is for a release that has a tree and does not want

package/bin/content-build.mjs

@@ -47,6 +47,7 @@
  *   npx content-build markdown [paths..] [--fix]
  *   npx content-build manifest [root] [--out <dir>]
  *   npx content-build site [--out <dir>]
+ *   npx content-build map [--tree] [--from <shortcode>] [--chart <shortcode>] [--travel] [--out <dir>]
  *   npx content-build reachability <dir> [file] [--index <shortcode>]
  *   npx content-build addresses diff --from <zip|dir> [--strict]
  *
@@ -144,6 +145,10 @@ import {
     addressFindingMessage,
 } from "../engine/address-diff.mjs";
 import { emittedArtFor, itemPackJsonDirs } from "../engine/generate.mjs";
+import { buildMaps, FROM_ALL, MAP_DIR } from "../engine/map-build.mjs";
+import { CHART_HORIZON_DAYS } from "../engine/map-layout.mjs";
+import { GRAPHVIZ_ENGINES } from "../engine/map-graphviz.mjs";
+import { loadMapWorld } from "../engine/map-places.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -250,6 +255,7 @@ const argv = yargs(hideBin(process.argv))
     .command(contentIndexCommand())
     .command(siteCommand())
     .command(pdfCommand())
+    .command(mapCommand())
     .command(reachabilityCommand())
     .command(addressesCommand())
     .version(ownVersion())
@@ -1663,6 +1669,163 @@ function siteCommand() {
     };
 }
 
+/**
+ * `content-build map` — draw what the place notes state.
+ *
+ * Reads the content index — this package's and every declared dependency's —
+ * so a consumer's map draws its dependencies' places beside its own, and
+ * writes under `build/map/`, always the `.dot` beside the `.svg`. Four
+ * drawings: the containment tree from `parents` (`--tree`, the author's
+ * check, whose anomalies are reported as findings), the map from a place
+ * from its `borders` and `routes` (`--from`), the chart from a place — the
+ * same drawing at a larger horizon (`--chart`, `--horizon`) — and the whole
+ * route graph (`--travel`). GraphViz draws; when it is absent the command
+ * says what to install and stops.
+ *
+ * @returns {object} The yargs command module.
+ */
+// eslint-disable-next-line
+function mapCommand() {
+    return {
+        command: "map",
+        describe:
+            "Draw the containment tree, the map or the chart from a place, or the route graph",
+        builder: (yargs) => {
+            yargs
+                .option("tree", {
+                    describe:
+                        "Draw the containment tree from `parents`: `tree.svg`, and one " +
+                        "`tree-<shortcode>.svg` per continent. Reports the anomalies.",
+                    type: "boolean",
+                    default: false,
+                })
+                .option("root", {
+                    describe:
+                        "With --tree, draw the subtree beneath this place as " +
+                        "`tree-<shortcode>.svg` and report nothing.",
+                    type: "string",
+                })
+                .option("from", {
+                    describe:
+                        "Draw the map from this place as `from-<shortcode>.svg`; repeatable, " +
+                        `or \`${FROM_ALL}\` for every place with a border or a route.`,
+                    type: "string",
+                    array: true,
+                })
+                .option("chart", {
+                    describe:
+                        "Draw the chart from this place as `chart-<shortcode>.svg` — the map " +
+                        "from it at a larger horizon, the hops chaining on; repeatable, " +
+                        `or \`${FROM_ALL}\` for every place with a border or a route.`,
+                    type: "string",
+                    array: true,
+                })
+                .option("horizon", {
+                    describe:
+                        "The charts' horizon in days, a marker of the scale: rings are " +
+                        "drawn to it, and a place farther than it is left out.",
+                    type: "number",
+                    default: CHART_HORIZON_DAYS,
+                })
+                .option("travel", {
+                    describe: "Draw the whole route graph as `travel.svg`.",
+                    type: "boolean",
+                    default: false,
+                })
+                .option("engine", {
+                    describe: "The tree's layout engine. `twopi` is the radial one.",
+                    choices: [...GRAPHVIZ_ENGINES],
+                    default: "dot",
+                })
+                .option("rankdir", {
+                    describe: "The tree's rank direction; `dot` engine only.",
+                    choices: ["TB", "LR", "BT", "RL"],
+                    default: "TB",
+                })
+                .option("nodesep", {
+                    describe: "The tree's GraphViz `nodesep`, in inches.",
+                    type: "number",
+                })
+                .option("ranksep", {
+                    describe: "The tree's GraphViz `ranksep`, in inches.",
+                    type: "number",
+                })
+                .option("scale", {
+                    describe: "Multiply every node's size, font and border weight.",
+                    type: "number",
+                    default: 1,
+                })
+                // Declared positively so yargs derives `--no-polities` from it.
+                .option("polities", {
+                    describe:
+                        "Draw polities beside their regions in the tree. `--no-polities` " +
+                        "drops them.",
+                    type: "boolean",
+                    default: true,
+                })
+                .option("base", {
+                    describe:
+                        "The site base this package's pages are served under, ending in " +
+                        "a slash; given, every name is a link to its page.",
+                    type: "string",
+                })
+                .option("out", {
+                    describe: `Directory to write into. Defaults to \`${MAP_DIR}\`.`,
+                    type: "string",
+                });
+        },
+        handler: (argv) => {
+            try {
+                const config = loadPackConfig();
+                const outDir = argv.out ?? path.join(config.rootDir, ...MAP_DIR.split("/"));
+                const problems = [];
+                const world = loadMapWorld({ config, base: argv.base, problems });
+                for (const problem of problems) emitDiagnostic(problem);
+                if (problems.length) process.exitCode = 1;
+                for (const s of world.stale) {
+                    emitDiagnostic({
+                        file: cachedIndexPath(config, s.package),
+                        severity: "error",
+                        message: `unusable content index: ${s.reason}`,
+                    });
+                }
+                if (world.stale.length) {
+                    log.error("Re-run `content-build deps fetch`.");
+                    process.exitCode = 1;
+                    return;
+                }
+
+                const result = buildMaps({
+                    world,
+                    outDir,
+                    tree: argv.tree,
+                    root: argv.root,
+                    from: argv.from ?? [],
+                    chart: argv.chart ?? [],
+                    horizon: argv.horizon,
+                    travel: argv.travel,
+                    engine: argv.engine,
+                    rankdir: argv.rankdir,
+                    nodesep: argv.nodesep,
+                    ranksep: argv.ranksep,
+                    scale: argv.scale,
+                    polities: argv.polities !== false,
+                });
+                const errors = reportFindings(result.findings, {});
+                const svgs = result.written.filter((f) => f.endsWith(".svg"));
+                log.info(
+                    `${world.places.size} place(s) → ${svgs.length} drawing(s) under ` +
+                        `${path.relative(process.cwd(), outDir) || "."}`,
+                );
+                if (errors) process.exitCode = 1;
+            } catch (err) {
+                reportFailure(err);
+                process.exitCode = 1;
+            }
+        },
+    };
+}
+
 /**
  * `content-build reachability <dir> [file]` — check that a corpus reads through.
  *

package/bin/package-build.mjs

@@ -456,19 +456,21 @@ function manifestCommand() {
 }
 
 /**
- * `package-build site-root` — the deployment's root files.
+ * `package-build site-root` — the deployment's root files, and the search
+ * index.
  *
  * Hugo owns everything under the `/<package>/` prefix; this owns what sits
  * beside it, which is what Cloudflare Pages reads from the uploaded directory
  * and nowhere else: `_headers`, and no `_redirects`, since the prefix root is
- * the homepage.
+ * the homepage. It then indexes the rendered pages for search into
+ * `<package>/pagefind/`, unless `site.search` is off.
  *
  * @returns {object} The yargs command.
  */
 function siteRootCommand() {
     return {
         command: "site-root",
-        describe: "Write the deployment's _headers",
+        describe: "Write the deployment's _headers and index the site for search",
         builder: (y) =>
             y.option("out", {
                 type: "string",
@@ -479,10 +481,22 @@ function siteRootCommand() {
             const shared = loadPackConfig();
             const out = path.resolve(config.rootDir, argv.out ?? DEPLOY_ROOT);
 
-            const { files } = writeSiteRoot({ pkg: shared.contentPackage, out });
+            const { files, search } = await writeSiteRoot({
+                pkg: shared.contentPackage,
+                out,
+                search: shared.site.search,
+            });
             for (const file of files) {
                 console.log(`✅ Wrote ${path.relative(config.rootDir, file)}.`);
             }
+            if (search) {
+                console.log(
+                    `✅ Indexed ${search.pages} pages for search into ` +
+                        `${path.relative(config.rootDir, search.dir)}/.`,
+                );
+            } else {
+                console.log("Search is off (`site.search: false`), so no index was written.");
+            }
         }),
     };
 }

package/content-config.mjs

@@ -771,6 +771,7 @@ const SITE_KEYS = [
     "passOptions",
     "notfound",
     "hugo",
+    "search",
 ];
 const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
 const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
@@ -1710,6 +1711,10 @@ const SITE_INDEX_MESSAGE =
  * shared with the link manifest so the two cannot disagree about where a
  * page is.
  *
+ * `search` is the one switch here: whether `package-build site-root` writes a
+ * search index beside the rendered pages. On by default — every site carries
+ * one unless it says otherwise.
+ *
  * **What the site publishes is the homepage and the content tree, and nothing
  * beside them.** A page of documentation is a note — `type: doc`, addressed
  * by its shortcode, compiling into no document where it says `pack: none` —
@@ -1733,6 +1738,7 @@ function normalizeSite(value) {
         passOptions: Object.freeze({}),
         notfound: null,
         hugo: Object.freeze({}),
+        search: true,
     });
     if (value === undefined) return empty;
     if (!isPlainObject(value)) fail("site", "must be a mapping");
@@ -1788,6 +1794,7 @@ function normalizeSite(value) {
             :   Object.freeze({ ...input.passOptions }),
         notfound: normalizeSiteNotfound(input.notfound),
         hugo: normalizeSiteHugo(input.hugo),
+        search: optionalBoolean(input.search, "site.search", true),
     });
 }
 

package/docs/api.md

@@ -412,6 +412,94 @@ Drawing a declared infobox: HTML for a Foundry Journal Page, Typst for the book.
 | `linkToUuid`           | `linkToUuid(value)`                   | `string`  | drawing a link value as a Foundry document reference                     |
 | `sectionHasContent`    | `sectionHasContent(section)`          | `boolean` | deciding whether a section holds anything worth drawing                  |
 
+### `engine.placeRelations`
+
+What a place is next to (`data.borders`) and reachable from (`data.routes`): the closed sets both draw from, stated once for the lint, the specification and a consumer drawing a map, and the checks that hold a note to them and to the note at the other end.
+
+| Export            | Signature                       | Returns             | Use it when                                                                                                          |
+| ----------------- | ------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `BEARINGS`        | `const BEARINGS`                | `readonly string[]` | the eight compass bearings, clockwise from `N`                                                                       |
+| `ROUTE_MODES`     | `const ROUTE_MODES`             | `readonly string[]` | the modes a route is travelled by — `land`, `boat`, `ship`                                                           |
+| `TRAVEL_DAYS`     | `const TRAVEL_DAYS`             | `readonly number[]` | the days markers a route may state, each meaning "about this, under normal conditions"                               |
+| `TERRAIN_MODES`   | `const TERRAIN_MODES`           | —                   | the terrain registry, each terrain naming the modes that cross it                                                    |
+| `TERRAINS`        | `const TERRAINS`                | `readonly string[]` | the terrain names, in registry order                                                                                 |
+| `BORDER_KEYS`     | `const BORDER_KEYS`             | `readonly string[]` | the keys a `borders` entry carries                                                                                   |
+| `ROUTE_KEYS`      | `const ROUTE_KEYS`              | `readonly string[]` | the keys a `routes` entry carries                                                                                    |
+| `oppositeBearing` | `oppositeBearing(bearing)`      | `string\|undefined` | the bearing the other end of a relation states, or `undefined` for a value that is not a bearing                     |
+| `checkBorders`    | `checkBorders(note, { index })` | `object[]`          | linting a place's `borders` — targets, values, once per pair, no parent or child, and reciprocity with the other end |
+| `checkRoutes`     | `checkRoutes(note, { index })`  | `object[]`          | linting a place's `routes` — as `checkBorders`, plus `mode`, `days` and `terrain`, once per pair per mode            |
+
+### `engine.mapPlaces`
+
+The places a map is drawn from — this package's index records and every fetched dependency's entries, read through one shape — and what their `parents` say: the world, the continents, each place's continent, and everything the containment tree can get wrong, reported as findings located at the entry that states it.
+
+| Export                | Signature                                                        | Returns       | Use it when                                                                                                              |
+| --------------------- | ---------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `placesFromRecords`   | `placesFromRecords(records, { contentBase, base })`              | `MapWorld`    | reading this package's places and polities out of its index records, with a page URL each where a site base is given     |
+| `loadMapWorld`        | `loadMapWorld({ config, contentBase, base, problems })`          | `MapWorld`    | loading the world a map is drawn from — this package's index and every declared dependency's                             |
+| `analyzeContainment`  | `analyzeContainment(places, polities)`                           | `Containment` | finding the world, the continents, each place's continent and the anomalies of `parents`                                 |
+| `subtreeOf`           | `subtreeOf(analysis, root)`                                      | `Set<string>` | every place beneath one, by following `parents` downward                                                                 |
+| `containmentFindings` | `containmentFindings(analysis, places, { contentBase, config })` | `object[]`    | the anomalies as `file:line:column: severity: message` findings — no parent, an unresolved parent and a cycle are errors |
+
+### `engine.mapLayout`
+
+The geometry of the map from a place and of the chart from one, as arithmetic over the place records: north up, east right, the angle from the bearing and the radius from the days marker on log-spaced rings, hops composed into one bearing as long as none turns back. Nothing here touches a file or GraphViz.
+
+| Export               | Signature                                  | Returns             | Use it when                                                                                                                   |
+| -------------------- | ------------------------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `HORIZON_DAYS`       | `const HORIZON_DAYS`                       | `number`            | the horizon of the map from a place, 90 days; beyond it a place is a name at the rim                                          |
+| `CHART_HORIZON_DAYS` | `const CHART_HORIZON_DAYS`                 | `number`            | the horizon of the chart from a place when none is asked for, 360 days — the end of the scale                                 |
+| `RING_DAYS`          | `const RING_DAYS`                          | `readonly number[]` | the days markers that are rings on the map from a place — every marker up to its horizon                                      |
+| `bearingAngle`       | `bearingAngle(bearing)`                    | `number\|undefined` | the angle of a bearing in degrees counter-clockwise from east — `N` is 90, `E` 0                                              |
+| `bearingVector`      | `bearingVector(bearing)`                   | `{x, y}\|undefined` | the unit vector of a bearing                                                                                                  |
+| `bearingSteps`       | `bearingSteps(a, b)`                       | `number\|undefined` | how many steps around the compass separate two bearings, the shorter way                                                      |
+| `rimRadius`          | `rimRadius(horizon?)`                      | `number`            | the radius of the rim, one log step beyond the horizon — the map from a place's by default                                    |
+| `ringRadius`         | `ringRadius(days, horizon?)`               | `number`            | the radius of the ring a days value sits on — the rim for none, or for a value beyond the horizon                             |
+| `rings`              | `rings(horizon?)`                          | `object[]`          | the rings inside out, each marker up to the horizon with its radius                                                           |
+| `daysMarker`         | `daysMarker(total)`                        | `number\|undefined` | the smallest marker of the scale that covers a total of days                                                                  |
+| `edgeLength`         | `edgeLength(days)`                         | `number`            | the length a route asks of `neato` in the route graph, inches, on the rings' log scale                                        |
+| `composeChain`       | `composeChain(hops)`                       | `object\|undefined` | a chain of hops composed into one bearing and one total, each hop within an octant of the running direction, else `undefined` |
+| `composeHops`        | `composeHops(first, second)`               | `object\|undefined` | two hops composed into one bearing and one total where they agree — the same bearing or adjacent — else `undefined`           |
+| `relationsOf`        | `relationsOf(places, shortcode)`           | `object`            | every border and route touching one place, read from both ends, plus the targets that resolved to nothing                     |
+| `layoutFrom`         | `layoutFrom(places, centre)`               | `object`            | laying out the map from a place: every node pinned in points, every edge, the rings and the rim                               |
+| `layoutChart`        | `layoutChart(places, centre, { horizon })` | `object`            | laying out the chart from a place: the map from it at a larger horizon, the hops chaining on as long as none turns back       |
+| `travelGraph`        | `travelGraph(places)`                      | `object`            | the whole route graph — one edge per pair, however many ends and modes state it, each with a length from its days             |
+
+### `engine.mapDot`
+
+The drawings of `content-build map` as DOT text, sharing one style table: shape, colour and size by `subType`, an anomaly overriding colour alone, every label a `name.full`, every tooltip an address, and a `URL` where the place carries one so the SVG's names are links.
+
+| Export       | Signature                                          | Returns  | Use it when                                                                                                      |
+| ------------ | -------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
+| `STYLE`      | `const STYLE`                                      | —        | the shape, colour and size of each `subType`, and of a polity                                                    |
+| `dotString`  | `dotString(value)`                                 | `string` | quoting text for DOT                                                                                             |
+| `treeDot`    | `treeDot({ places, polities, analysis, root, … })` | `string` | the containment tree — the whole world clustered by continent, or the subtree beneath `root`                     |
+| `hopOpacity` | `hopOpacity(hop)`                                  | `number` | how faint a place is drawn by its hop count — full to the second hop, a step down each hop beyond, floored       |
+| `fromDot`    | `fromDot(layout, places, { scale, title })`        | `string` | the map or the chart from a place, every node pinned for `neato -n2`, the rings drawn faintly with their markers |
+| `travelDot`  | `travelDot(graph, places, { scale, title })`       | `string` | the whole route graph for `neato`, each edge asking for a length from its days                                   |
+
+### `engine.mapGraphviz`
+
+GraphViz, as the map command reaches it: a build-time tool of that command alone, found once, named plainly when absent, and run over a `.dot` file the command keeps beside the rendering.
+
+| Export                   | Signature                                               | Returns             | Use it when                                                                                |
+| ------------------------ | ------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
+| `GRAPHVIZ_ENGINES`       | `const GRAPHVIZ_ENGINES`                                | `readonly string[]` | the engines the map command may ask for — `dot`, `twopi`, `neato`                          |
+| `findGraphviz`           | `findGraphviz(engine, { env, fallbacks })`              | `string\|undefined` | finding an engine's binary on `PATH` or in the directories a package manager installs into |
+| `graphvizMissingMessage` | `graphvizMissingMessage(engine)`                        | `string`            | saying an engine is not installed, and what installs it                                    |
+| `renderDot`              | `renderDot(dotPath, outPath, { binary, format, args })` | `{warnings}`        | rendering a `.dot` file, the engine's warnings returned and a non-zero exit thrown         |
+
+### `engine.mapBuild`
+
+`content-build map` as a function: the drawings written under an output directory, always the `.dot` beside the `.svg`, the tree's anomalies returned as findings, and a missing GraphViz either an error or — for a build that would rather skip — one warning.
+
+| Export          | Signature                                                                                                                                             | Returns                        | Use it when                                                                   |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
+| `MAP_DIR`       | `const MAP_DIR`                                                                                                                                       | `string`                       | where the maps land below a package's root, `build/map`                       |
+| `FROM_ALL`      | `const FROM_ALL`                                                                                                                                      | `string`                       | the `--from` or `--chart` value that means every place with a relation, `all` |
+| `relatedPlaces` | `relatedPlaces(places)`                                                                                                                               | `string[]`                     | every place that states, or is named in, a border or a route                  |
+| `buildMaps`     | `buildMaps({ world, outDir, tree, root, from, chart, horizon, travel, engine, rankdir, nodesep, ranksep, scale, polities, locate, requireGraphviz })` | `{written, findings, skipped}` | drawing any of the four from a loaded world                                   |
+
 ### `engine.systems`
 
 The closed registry of system ids, and the `none` that stands for no system at all. An unknown system value is an error; adding a system is a data change to this registry rather than a hardcoded set scattered through the pipeline.