@heroiclands/package-build 22.4.5 → 22.4.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @heroiclands/package-build
 
+## 22.4.7
+
+### Patch Changes
+
+Every place page that states a border or a route, or is named in one, carries the map from that place: `from-<shortcode>.svg` beside the page and `map:` naming it in the front matter, with every place name on it a link to that place's page. GraphViz draws it; when GraphViz is not installed the site build says so once and writes every page without a map, and `site.maps: false` draws none.
+
+A place's page carries what lies within it and who holds it, and an affiliation's page carries what it holds, read from the `parents` and `domains` the notes already state — a dependency's places and affiliations included. `content-build lint` warns of unheld land: a settlement, site or structure that no affiliation's `domains` names.
+
+A `place` note can state a settlement's market class: `data.market`, a whole number from 1 to 6 beside `population`. `1` is a hamlet, with no market beyond what neighbours trade among themselves; `2` a village and its weekly market; `3` a town with several trades working full time; `4` a market town, its chartered fair and its moneylender; `5` a city, where anything ordinary can be had in quantity; `6` a great city that banks, imports as a matter of course, and is the market from which the other markets buy. The key is optional, and a value off the scale is reported at the line that states it rather than rounded onto a class nobody wrote.
+
+## 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

package/CONTENT.md

@@ -1183,6 +1183,25 @@ 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`.
 
+**A settlement is held by someone.** An affiliation's `domains` names the
+places it holds, and a `place` of subType `settlement`, `site` or `structure`
+that no affiliation's `domains` names — in this tree or in a fetched index —
+is a warning, `unheld land`, at the note's `type:` line, so a gap in tenure
+shows. A region is held through its polity's `domains` and a feature by
+nobody, so neither is checked.
+
+**A settlement's market class is one of six.** `data.market` states what trade
+a settlement supports — `1` a hamlet, with no market beyond what neighbours
+trade among themselves; `2` a village and its weekly market; `3` a town with
+several trades working full time; `4` a market town, its chartered fair and its
+moneylender; `5` a city, where anything ordinary can be had in quantity; `6` a
+great city that banks, imports as a matter of course, and is the market from
+which the other markets buy. The numbers order the steps and do nothing else, so a value off the
+scale is an error at the value that states it rather than a number rounded onto
+a class the author did not write. The key is optional and the lint checks no
+`subType` condition, as it checks none for `population`. The scale is stated
+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
@@ -2409,6 +2428,96 @@ The theme's `related.html` partial reads both lists and renders them as one
 `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.
 
+### A place page says what lies within it and who holds it; an affiliation page says what it holds
+
+Two keys the notes already carry answer three questions a reader asks of a
+page. A place's `data.parents` is geography — what it sits within — and an
+affiliation's `data.domains` is tenure — what it holds. The build reads both
+across the tree and every fetched index, inverts them, and writes each page
+the lists that concern it, shaped like `related`:
+
+```yaml
+# on a place
+contains: # every place whose `parents` names this one
+  - title: Khaset-Mehtet
+    url: /thalorna/place-khasetmehtet/
+    type: place
+    subType: settlement
+held_by: # every affiliation whose `domains` names this one
+  - title: The Nome of Ankhsetun
+    url: /thalorna/affiliation-nomenkhstn/
+    type: affiliation
+    subType: polity
+
+# on an affiliation
+holdings: # every place its `domains` names
+  - title: Ankhsetun
+    url: /thalorna/place-ankhsetunnome/
+    type: place
+    subType: region
+```
+
+- **`contains` and `holdings` are sorted by `subType`, then `title`**;
+  `held_by` by `title`. An entry carries `subType` where the note declares
+  one.
+- **A key is present only when it has an entry.** A place nobody holds and
+  nothing sits within carries neither key; an affiliation whose `domains` is
+  empty carries no `holdings`. The theme's silent-disappear convention, kept
+  at the source.
+- **`domains` names what an affiliation holds directly, and is never
+  expanded.** A polity whose `domains` names a region holds the region; the
+  settlements within it are reached through the region's `contains`, and are
+  not repeated in the polity's `holdings`. Tenure runs through
+  `affiliation.parents` — a house of its earl, an earl of the crown — and
+  geography through `place.parents`. A subinfeudated manor sits in one region
+  by the second and under a lord of another polity by the first, and both
+  pages say so.
+- **A dependency's places and affiliations take part.** A fetched index entry
+  carries the `parents` and `domains` its record stated, so a place another
+  package publishes is listed within a local region, and a house another
+  package publishes is named on the local manor it holds. A local note
+  declaring a shortcode shadows a fetched entry declaring the same one.
+- **`url` composes `<base><slug>/`**, as every `related` entry does.
+
+All three are derived, never authored: a note that writes one has it
+replaced. The theme renders each list as a table on the page.
+
+### A place page carries the map from that place
+
+A place that states a border or a route, or is named in one, has a map from
+it — the drawing `content-build map --from` makes, with the place at the
+centre and each neighbour at its bearing. The site build draws that map for
+every such place and writes it with the page: the page is a leaf bundle,
+`place-<shortcode>/index.md`, the drawing sits beside it as
+`from-<shortcode>.svg`, and the front matter names it:
+
+```yaml
+map: from-kthrmr.svg
+```
+
+The theme's "From here" panel reads the key, inlines the file as a page
+resource, and so every place name on the map is a link to that place's page.
+What the build guarantees:
+
+- **The address does not move.** A bundled page states the same `url` a flat
+  one does, `/<slug>/`, so `place-kthrmr/index.md` publishes exactly where
+  `place-kthrmr.md` would.
+- **Every name links through the site base.** The map is drawn with the base
+  the pages are served under, so each `href` composes `<base><slug>/` the way
+  every other href the build renders does.
+- **It is written for inlining.** No XML prologue, no DOCTYPE, no comment, no
+  reference to anything outside the file; the root carries a `viewBox` and no
+  fixed width or height, so the theme sizes it to the column.
+- **A place with no relation carries nothing**: no file beside it, no `map`
+  key, and the page stays a flat file. So does every page that is not a place.
+- **A site never fails for want of a map.** GraphViz draws; when it is not
+  installed the build says so once, as a warning naming what to install, and
+  every page is written as it would be without maps. `site.maps: false` in
+  `package-build.config.yaml` draws nothing and asks nothing of GraphViz.
+
+`map` is derived, never authored: a note that writes one has it replaced when
+the build draws a map, and dropped when there is none to draw.
+
 ### Why the output location is fixed
 
 The content mount is a build artifact and is **deleted on every run**, so that a

package/bin/content-build.mjs

@@ -47,7 +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 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]
  *
@@ -146,6 +146,7 @@ import {
 } 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";
 
@@ -1514,7 +1515,8 @@ function pdfCommand() {
  * wikilink resolution, code-fence protection and the foreign-manifest merge —
  * happens here, from configuration. So does the Hugo configuration: the whole
  * source tree Hugo reads lands under `build/hugo/`, and the consumer's script
- * runs Hugo over it.
+ * runs Hugo over it. With `site.maps` on and GraphViz installed, every place
+ * page with a border or a route carries the map from that place.
  *
  * **The Hugo configuration is generated before anything is written.** Its
  * sources — `package.json`'s `homepage`, the cached navigation, the installed
@@ -1652,10 +1654,17 @@ function siteCommand() {
                     return;
                 }
 
+                // What drawing the maps found: warnings, every one. A site
+                // never fails for want of a map, so none of these touches the
+                // exit code — GraphViz absent is one line naming what to
+                // install, and every page is written as it would be without.
+                for (const f of result.mapFindings) emitDiagnostic(f);
+
                 const s = result.stats;
                 log.info(
                     `wrote ${s.homepages ?? 0} homepage(s) + ` +
-                        `${s.content ?? 0} content page(s) to ` +
+                        `${s.content ?? 0} content page(s), ` +
+                        `${s.maps ?? 0} with a map, to ` +
                         `${path.relative(process.cwd(), s.out)}`,
                 );
                 const { file } = writeHugoConfig(config, hugo);
@@ -1673,12 +1682,13 @@ function siteCommand() {
  *
  * 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
+ * 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`), and the whole route graph
- * (`--travel`). GraphViz draws; when it is absent the command says what to
- * install and stops.
+ * 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.
  */
@@ -1686,7 +1696,8 @@ function siteCommand() {
 function mapCommand() {
     return {
         command: "map",
-        describe: "Draw the containment tree, the map from a place, or the route graph",
+        describe:
+            "Draw the containment tree, the map or the chart from a place, or the route graph",
         builder: (yargs) => {
             yargs
                 .option("tree", {
@@ -1709,6 +1720,21 @@ function mapCommand() {
                     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",
@@ -1783,6 +1809,8 @@ function mapCommand() {
                     tree: argv.tree,
                     root: argv.root,
                     from: argv.from ?? [],
+                    chart: argv.chart ?? [],
+                    horizon: argv.horizon,
                     travel: argv.travel,
                     engine: argv.engine,
                     rankdir: argv.rankdir,

package/content-config.mjs

@@ -772,6 +772,7 @@ const SITE_KEYS = [
     "notfound",
     "hugo",
     "search",
+    "maps",
 ];
 const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
 const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
@@ -1711,9 +1712,11 @@ 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.
+ * Two switches sit here, both on by default. `search` is whether
+ * `package-build site-root` writes a search index beside the rendered pages.
+ * `maps` is whether `content-build site` draws the map from each place that
+ * states a border or a route and writes it into that place's page — a site
+ * carries both 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
@@ -1739,6 +1742,7 @@ function normalizeSite(value) {
         notfound: null,
         hugo: Object.freeze({}),
         search: true,
+        maps: true,
     });
     if (value === undefined) return empty;
     if (!isPlainObject(value)) fail("site", "must be a mapping");
@@ -1795,6 +1799,7 @@ function normalizeSite(value) {
         notfound: normalizeSiteNotfound(input.notfound),
         hugo: normalizeSiteHugo(input.hugo),
         search: optionalBoolean(input.search, "site.search", true),
+        maps: optionalBoolean(input.maps, "site.maps", true),
     });
 }
 

package/docs/api.md

@@ -429,6 +429,30 @@ What a place is next to (`data.borders`) and reachable from (`data.routes`): the
 | `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.holdings`
+
+What lies within a place, who holds it, and what an affiliation holds — read off `data.parents` and `data.domains` across this package and every fetched index, inverted into the `contains`, `held_by` and `holdings` lists the site build writes — and the tenure check `content-build lint` runs on a place.
+
+| Export                 | Signature                            | Returns                 | Use it when                                                                                                                  |
+| ---------------------- | ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `HOLDINGS_KEYS`        | `const HOLDINGS_KEYS`                | `readonly string[]`     | the three derived keys — `contains`, `held_by`, `holdings` — which a note cannot author                                      |
+| `HELD_SUBTYPES`        | `const HELD_SUBTYPES`                | `readonly string[]`     | the place subTypes tenure is checked on — `settlement`, `site`, `structure`                                                  |
+| `holdingsNode`         | `holdingsNode(fm, { title, url })`   | `HoldingsNode\|null`    | reading a local note as a node of the derivation, or `null` for one that is neither a place nor an affiliation               |
+| `foreignHoldingsNodes` | `foreignHoldingsNodes(foreignIndex)` | `HoldingsNode[]`        | reading a fetched index's places and affiliations as nodes                                                                   |
+| `holdingsPages`        | `holdingsPages(nodes)`               | `Map<string, Holdings>` | inverting `parents` and `domains` into each page's sorted lists, keyed by URL, for every page with at least one entry        |
+| `checkHeld`            | `checkHeld(note, { index })`         | `object[]`              | linting a place's tenure — a settlement, site or structure no affiliation's `domains` names is a warning at its `type:` line |
+
+### `engine.marketClass`
+
+What trade a settlement supports (`data.market`): the six-step scale, stated once for the lint, the author-facing reference and the specification, and the check that holds a note's value to it.
+
+| Export           | Signature              | Returns             | Use it when                                                                                       |
+| ---------------- | ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
+| `MARKET_CLASSES` | `const MARKET_CLASSES` | `readonly object[]` | the scale in order, each step its `value`, the `name` a settlement of it goes by, and its `trade` |
+| `isMarketClass`  | `isMarketClass(value)` | `boolean`           | asking whether an authored value names a class, a quoted number included                          |
+| `marketClass`    | `marketClass(value)`   | `object\|undefined` | the class a value names, for rendering what a number means                                        |
+| `checkMarket`    | `checkMarket(note)`    | `object[]`          | linting a place's `market` — a value off the scale, located at the value that states it           |
+
 ### `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.
@@ -437,42 +461,47 @@ The places a map is drawn from — this package's index records and every fetche
 | --------------------- | ---------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | `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                             |
+| `mapWorld`            | `mapWorld({ records, foreignIndex, contentBase, base, config })` | `MapWorld`    | the same world out of records and indexes a caller already holds, as the site build does                                 |
 | `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   |
+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 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.
+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`        |
-| `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                      |
+| 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`
 
@@ -481,6 +510,7 @@ GraphViz, as the map command reaches it: a build-time tool of that command alone
 | Export                   | Signature                                               | Returns             | Use it when                                                                                |
 | ------------------------ | ------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
 | `GRAPHVIZ_ENGINES`       | `const GRAPHVIZ_ENGINES`                                | `readonly string[]` | the engines the map command may ask for — `dot`, `twopi`, `neato`                          |
+| `GRAPHVIZ_INSTALL`       | `const GRAPHVIZ_INSTALL`                                | `string`            | what installs GraphViz, as the clause every "not installed" message ends with              |
 | `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         |
@@ -489,12 +519,22 @@ GraphViz, as the map command reaches it: a build-time tool of that command alone
 
 `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                     |
+| 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.siteMaps`
+
+The map from each place, drawn for the site: `content-build site` draws the map from every place of this package that states, or is named in, a border or a route — with the site's base, so every name links through it — and the page writer lays each drawing beside its page as `from-<shortcode>.svg` and names it in the front matter as `map`. GraphViz absent is one warning and no map; `site.maps: false` draws none.
+
+| Export         | Signature                                                       | Returns            | Use it when                                                                                                     |
+| -------------- | --------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `SITE_MAP_DIR` | `const SITE_MAP_DIR`                                            | `string`           | where the site build draws below a package's root, `build/map/site`                                             |
+| `inlineSvg`    | `inlineSvg(svg)`                                                | `string`           | rewriting a GraphViz SVG for inlining — no prologue, no comment, no `xlink:`, the root sized by `viewBox` alone |
+| `drawSiteMaps` | `drawSiteMaps({ records, foreignIndex, config, base, locate })` | `{maps, findings}` | drawing the map from every related place of this package, keyed by the URL of the page that carries it          |
 
 ### `engine.systems`
 
@@ -690,20 +730,20 @@ The toolchain's own content index — the files it ships, addressed. Every other
 
 Publishing a content tree as a website. Compiling a content tree into compendium packs is `content-build package compile`. Publishing the _same tree_ as a website was a script each consumer wrote for itself — 473 code lines in `sohl` and 462 in `sohl-thalorna`, 87 of them identical — and the copies drifted in ways neither repository could see. `sohl-thalorna` reimplemented four things this package already exported, not because it needed different behaviour but because its script predates the extraction. That is the failure a command removes: a consumer cannot accidentally reimplement one.
 
-| Export                | Signature                                         | Returns                                                                                                                                | Use it when                                                                |
-| --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `collectContentPages` | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                 |
-| `collectHomepages`    | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.  |
-| `writeHomepages`      | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage as the package root's `_index.md`.                    |
-| `siteGates`           | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.           |
-| `emptyGates`          | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                          |
-| `gatesFailed`         | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                       |
-| `tableUniverse`       | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.               |
-| `pageFrontmatter`     | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                     |
-| `pageDestination`     | `function pageDestination(page)`                  | —                                                                                                                                      | Where a page is written, relative to the output root.                      |
-| `renderPages`         | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                             |
-| `resolveSitePass`     | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                        |
-| `buildSite`           | `buildSite({ config, sqlTables })`                | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], manifests: object\|null}}                           | Builds a Hugo content tree from a content tree, and reports what it found. |
+| Export                | Signature                                         | Returns                                                                                                                                | Use it when                                                                                                           |
+| --------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `collectContentPages` | `function collectContentPages(contentBase, ctx)`  | {{pages: object[], addressFindings: object[], fmLinkFindings: object[]}}                                                               | The content tree's pages, and what could not be addressed.                                                            |
+| `collectHomepages`    | `function collectHomepages(contentBase, ctx)`     | {{pages: object[], addressFindings: object[]}} The homepage notes, in walk order, and the ones among them that could not be addressed. | The package's homepage notes — the authored page at `/<contentPackage>/`.                                             |
+| `writeHomepages`      | `function writeHomepages(outRoot, pages, config)` | {number} How many pages were written.                                                                                                  | Writes each homepage as the package root's `_index.md`.                                                               |
+| `siteGates`           | `function siteGates(pages, findings,`             | {object} The gate results and, when they pass, the built index.                                                                        | The integrity gates a site build runs before it writes anything.                                                      |
+| `emptyGates`          | `function emptyGates()`                           | {object} An all-clear gate result.                                                                                                     | The gate result of a build that ran none of them.                                                                     |
+| `gatesFailed`         | `function gatesFailed(gates)`                     | —                                                                                                                                      | Whether any gate produced a finding.                                                                                  |
+| `tableUniverse`       | `function tableUniverse(pages)`                   | {Map<string, object[]>} Package → the notes it may tabulate.                                                                           | The universe a generated table searches, grouped by package.                                                          |
+| `pageFrontmatter`     | `function pageFrontmatter(page,`                  | {object} The frontmatter to write.                                                                                                     | The frontmatter a page publishes with.                                                                                |
+| `pageDestination`     | `function pageDestination(page, { bundle })`      | —                                                                                                                                      | Where a page is written, relative to the output root: flat, or as a leaf bundle when it carries a file beside itself. |
+| `renderPages`         | `function renderPages(pages, options)`            | {{written: number, byKind: Record<string, number>, tableErrors: object[], wikiErrors: object[]}}                                       | Renders and writes every page.                                                                                        |
+| `resolveSitePass`     | `function resolveSitePass(name, options)`         | {{beforeLinks?: Function}} The bundle.                                                                                                 | Resolves `site.pass` to its bundle.                                                                                   |
+| `buildSite`           | `buildSite({ config, sqlTables, locate })`        | {{gates: object, stats: object\|null, tableErrors: object[], wikiErrors: object[], mapFindings: object[], manifests: object\|null}}    | Builds a Hugo content tree from a content tree, and reports what it found.                                            |
 
 ### `engine.contentLint`