@heroiclands/package-build 22.4.3 → 22.4.5

package/CHANGELOG.md

@@ -1,45 +1,55 @@
 # @heroiclands/package-build
 
+## 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
+
+Every page a site build publishes carries a `related` block in its front matter — the pages that link to it and the pages it links to, each named once with its title, address and type — which the theme renders as the Related card at the foot of the page. A page nothing connects to carries no block, and the homepage is counted on both sides like any other page.
+
+`changelog group` keeps a hard-wrapped paragraph as one block instead of fragmenting it one block per line, and no longer inserts a blank line under a bold sentence a paragraph continues directly beneath.
+
 ## 22.4.3
 
 ### Patch Changes
 
+**A new `changelog group` command folds a release's changeset blocks together by their bold label.**
 `@heroiclands/package-build/changelog` writes each changeset's summary into `CHANGELOG.md` as its
-
 own block, so three pull requests each touching compendium content leave three separate
-
 `**Compendiums**` blocks instead of one. `changelog group` rewrites the newest release section in
-
 place: every block sharing one label is merged into a single block, bullets kept in their original
-
 order with an exact duplicate kept once, and the merged blocks are ordered by a new
-
 `changelog.labels` configuration key — the unlabelled lead paragraph first, then every declared
-
 label in order, then any undeclared label last with a warning naming it. `changelog check` warns on
-
 a label absent from a declared `changelog.labels` too, so a drifted spelling is caught before a
-
 release ships it.
 
+**A shipped changelog generator writes a release note without a commit hash.**
 `@heroiclands/package-build/changelog` is a Changesets changelog generator
-
 whose `getReleaseLine` renders a changeset's summary as a block, verbatim —
-
 no bullet, no indentation, separated from its neighbours by one blank line —
-
 and whose `getDependencyReleaseLine` writes nothing. Point
-
 `.changeset/config.json` at it
-
 (`"changelog": "@heroiclands/package-build/changelog"`) to stop every release
-
 note from carrying a commit-hash prefix.
 
-**A new `changelog group` command folds a release's changeset blocks together by their bold label.**
-
-**A shipped changelog generator writes a release note without a commit hash.**
-
 ## 22.4.2
 
 ### 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
 
@@ -2333,6 +2362,53 @@ notes it lists, and link it from the homepage. Nothing is generated between
 the homepage and the pages, so delete the key.
 ````
 
+### Every page carries what links to it, and what it links to
+
+The build resolves every wikilink on every page through the address index, so
+at the moment it writes a page it holds the whole link graph. It writes the
+part that concerns each page into that page's front matter:
+
+```yaml
+related:
+  backlinks: # pages that link to this one
+    - title: Afzandah Parnâzar
+      url: /thalorna/being-afzndhprnzr/
+      type: being
+  mentions: # pages this one links to
+    - title: Kethramír
+      url: /thalorna/place-kthrmr/
+      type: place
+```
+
+The theme's `related.html` partial reads both lists and renders them as one
+"Related" card, grouped by `type`. What the build guarantees about them:
+
+- **A page appears once per list**, however many times it is linked, and
+  whichever address the link was written to: `docbeing-grod` and `being-grod`
+  are one page, and a page that cites it under both lists it once. A link from
+  a page to itself is not a connection and is dropped.
+- **Each list is sorted by `type`, then `title`**, so the card's grouping is
+  the same on every build whatever order the notes were walked in.
+- **Both lists are present whenever either has an entry**, so a theme reads one
+  shape; a page with no links either way carries **no `related` key at all**,
+  which is the partial's silent-disappear convention kept at the source.
+- **`url` composes `<base><slug>/`**, like every other href this build renders
+  — see [A page's URL is its address](#a-pages-url-is-its-address). The page
+  states its own address as `/<slug>/`; everything pointing _at_ it, this
+  included, carries the base.
+- **The homepage is a page like any other on both sides.** A content page
+  reaches it through `[[homepage-root|Text]]` and is listed in its backlinks;
+  its own body links are ordinary markdown, resolved against the package root
+  the way a browser resolves them, so `being-grod/`, `/thalorna/being-grod/`
+  and `./being-grod/#top` each count as a mention of that page. A link that
+  names a host leaves the site and counts as nothing.
+- **Only a page of this site is an endpoint.** A link into another package
+  resolves to an href the build renders but no page it writes, so it is listed
+  on neither side; a backlink can be counted only on a page this build emits.
+
+`related` is derived, never authored: what links to a page is a fact about
+every other page in the tree. A note that writes one has it replaced.
+
 ### Why the output location is fixed
 
 The content mount is a build artifact and is **deleted on every run**, so that a

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>] [--travel] [--out <dir>]
  *   npx content-build reachability <dir> [file] [--index <shortcode>]
  *   npx content-build addresses diff --from <zip|dir> [--strict]
  *
@@ -144,6 +145,9 @@ 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 { GRAPHVIZ_ENGINES } from "../engine/map-graphviz.mjs";
+import { loadMapWorld } from "../engine/map-places.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -250,6 +254,7 @@ const argv = yargs(hideBin(process.argv))
     .command(contentIndexCommand())
     .command(siteCommand())
     .command(pdfCommand())
+    .command(mapCommand())
     .command(reachabilityCommand())
     .command(addressesCommand())
     .version(ownVersion())
@@ -1663,6 +1668,144 @@ 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`. Three
+ * 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`), 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 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("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 ?? [],
+                    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,90 @@ 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, 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, two hops composed into one bearing only where they agree. 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                                |
+| `RING_DAYS`     | `const RING_DAYS`                | `readonly number[]` | the days markers that are rings — every marker up to the 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()`                    | `number`            | the radius of the rim, one log step beyond the horizon                                                              |
+| `ringRadius`    | `ringRadius(days)`               | `number`            | the radius of the ring a days value sits on — the rim for none, or for a value beyond the horizon                   |
+| `rings`         | `rings()`                        | `object[]`          | the rings inside out, each marker 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                              |
+| `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                     |
+| `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 three 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`        |
+| `fromDot`   | `fromDot(layout, places, { scale, title })`        | `string` | the map 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` 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, travel, engine, rankdir, nodesep, ranksep, scale, polities, locate, requireGraphviz })` | `{written, findings, skipped}` | drawing any of the three 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.