@heroiclands/package-build 22.14.3 → 22.15.0

package/engine/site-build.mjs

@@ -78,6 +78,7 @@ import { indexRecordsFor } from "./content-index.mjs";
 // A being's computed `age` — see `engine/being-age.mjs`. `pdf-build.mjs`
 // reuses `collectContentPages`'s pages, so wiring it here reaches the book too.
 import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 // The one statement of what an empty body means, shared with the index.
 import { isStubNote } from "./note-state.mjs";
@@ -196,19 +197,20 @@ export function collectContentPages(contentBase, ctx) {
     // The package's declared present, read once from the same corpus the site
     // and the PDF share — see `engine/being-age.mjs`. `pdf-build.mjs` reaches
     // this through the pages this function returns, so one call covers both.
-    const present = presentAmongRecords(
+    const records =
         ctx.records ??
-            indexRecordsFor({
-                contentBase,
-                config: ctx.config,
-                skipDirectories: ctx.skipDirectories,
-            }),
-    );
+        indexRecordsFor({
+            contentBase,
+            config: ctx.config,
+            skipDirectories: ctx.skipDirectories,
+        });
+    const present = presentAmongRecords(records);
+    const dates = reckoningContext({ notes: records });
 
     for (const file of siteCorpusFiles(contentBase, ctx)) {
         const note = readNote(file, ctx);
         if (!note) continue;
-        applyComputedBeingAge(note.fm, present);
+        applyComputedBeingAge(note.fm, present, dates);
         const { fm, body, bodyLine } = note;
         // The configuration's, never a note's: `package:` is retired, so every
         // note in the tree belongs to the package this repository compiles.
@@ -987,15 +989,12 @@ export function sitePageDecorator(config, index) {
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
- * @param {(engine: string) => string|undefined} [options.locate] - How a
- *   GraphViz engine's binary is found, for the maps; the real lookup by
- *   default.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[], mapFindings: object[],
  *   manifests: object|null}} `mapFindings` is what drawing the maps found —
  *   warnings, never a reason to fail the build.
  */
-export function buildSite({ config, sqlTables, locate } = {}) {
+export function buildSite({ config, sqlTables } = {}) {
     const resolved = config ?? loadPackConfig();
     const site = resolved.site;
     const scheme = resolved.publish.address;
@@ -1179,7 +1178,6 @@ export function buildSite({ config, sqlTables, locate } = {}) {
                 foreignIndex: gates.foreign.index,
                 config: resolved,
                 base,
-                ...(locate ? { locate } : {}),
             })
         :   { maps: new Map(), findings: [] };
 

package/engine/site-maps.mjs

@@ -23,10 +23,8 @@
  * and every `href` in it composes `<base><slug>/` the way every other href
  * the build renders does.
  *
- * GraphViz draws, and a site never fails for want of a map: when the engine is
- * absent the build says so once, as a warning, and writes every page as it
- * would without maps. `site.maps: false` says the site carries none and asks
- * nothing of GraphViz.
+ * The npm Graphviz runtime draws each map. `site.maps: false` says the site
+ * carries none and skips map rendering.
  *
  * The drawings land under `build/map/site/` — beside the author's own
  * drawings under `build/map/`, and apart from them, because the site's
@@ -40,7 +38,6 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { buildMaps, relatedPlaces } from "./map-build.mjs";
-import { GRAPHVIZ_INSTALL, findGraphviz } from "./map-graphviz.mjs";
 import { mapWorld } from "./map-places.mjs";
 
 /**
@@ -50,13 +47,6 @@ import { mapWorld } from "./map-places.mjs";
  */
 export const SITE_MAP_DIR = "build/map/site";
 
-/**
- * The engine the map from a place is drawn with.
- *
- * @type {string}
- */
-const ENGINE = "neato";
-
 /**
  * A drawing as the page writer receives it.
  *
@@ -106,16 +96,12 @@ export function inlineSvg(svg) {
  * @param {object} opts.config - The resolved configuration.
  * @param {string} opts.base - The site base every page is served under,
  *   ending in a slash: what every name in a drawing links through.
- * @param {(engine: string) => string|undefined} [opts.locate] - How the
- *   engine's binary is found; the real lookup by default.
  * @returns {{maps: Map<string, SiteMap>, findings: Array<{file: string,
  *   line?: number, column?: number, severity: "error"|"warning",
  *   message: string}>}} The drawings, keyed by the URL of the page each
- *   belongs to, and what the drawing found — one warning naming what to
- *   install when GraphViz is absent, and a warning for each relation that
- *   names no place.
+ *   belongs to, and warnings for relations that name no place.
  */
-export function drawSiteMaps({ records, foreignIndex, config, base, locate = findGraphviz }) {
+export function drawSiteMaps({ records, foreignIndex, config, base }) {
     /** @type {Map<string, SiteMap>} */
     const maps = new Map();
     const outDir = path.join(config.rootDir, ...SITE_MAP_DIR.split("/"));
@@ -123,22 +109,6 @@ export function drawSiteMaps({ records, foreignIndex, config, base, locate = fin
     // the map an earlier run drew.
     fs.rmSync(outDir, { recursive: true, force: true });
 
-    if (!locate(ENGINE)) {
-        return {
-            maps,
-            findings: [
-                {
-                    file: config.rootDir,
-                    severity: "warning",
-                    message:
-                        `GraphViz's \`${ENGINE}\` is not installed, so no place page carries ` +
-                        `the map from that place; ${GRAPHVIZ_INSTALL} to draw them, or set ` +
-                        "`site.maps: false` to say the site carries none",
-                },
-            ],
-        };
-    }
-
     const world = mapWorld({
         records,
         foreignIndex,
@@ -152,7 +122,7 @@ export function drawSiteMaps({ records, foreignIndex, config, base, locate = fin
     const centres = relatedPlaces(world.places).filter((s) => world.places.get(s)?.local);
     if (centres.length === 0) return { maps, findings: [] };
 
-    const { findings } = buildMaps({ world, outDir, from: centres, locate });
+    const { findings } = buildMaps({ world, outDir, from: centres });
     for (const centre of centres) {
         const place = world.places.get(centre);
         if (!place?.url) continue;

package/engine/site-preview.mjs

@@ -14,6 +14,7 @@ import { noteAddressContext, decodeNoteAddresses, encodeAddresses } from "./note
 import { noteFile } from "./index-records.mjs";
 import { foundryIdentities } from "./foundry-entries.mjs";
 import { applyComputedBeingAge, presentAmongRecords } from "./being-age.mjs";
+import { reckoningContext } from "./reckoning-markers.mjs";
 import { cachedMetadataIndexes, noContentIndexPackages } from "./metadata-index.mjs";
 import { buildSiteIndex } from "./site-index.mjs";
 import { openNotesDatabase, prepareSqlTables, findSqlBlocks } from "./sql-tables.mjs";
@@ -133,7 +134,11 @@ export async function prepareSitePreview({ config = loadPackConfig() } = {}) {
                     ...noteAddressContext(config),
                     package: config.contentPackage,
                 });
-                applyComputedBeingAge(fm, presentAmongRecords(snapshot.records));
+                applyComputedBeingAge(
+                    fm,
+                    presentAmongRecords(snapshot.records),
+                    reckoningContext({ notes: snapshot.records }),
+                );
             } catch (error) {
                 return {
                     ok: false,

package/engine/social-tie-terms.mjs

@@ -9,3 +9,6 @@ export const SOCIAL_TIES = Object.freeze([
     { term: "rival", meaning: "Opposes the subject without implacable hostility." },
     { term: "nemesis", meaning: "Opposes the subject personally and implacably." },
 ]);
+
+/** The note types a being can name as a social tie. */
+export const SOCIAL_TIE_TARGET_TYPES = Object.freeze(["being", "affiliation"]);

package/engine/social-ties.mjs

@@ -8,14 +8,13 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
-import { parseAddress, renderAddress } from "./address.mjs";
+import { acceptsType, parseAddress, renderAddress } from "./address.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
-import { SOCIAL_TIES } from "./social-tie-terms.mjs";
+import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 
-export { SOCIAL_TIES };
+export { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES };
 
 const TERMS = new Set(SOCIAL_TIES.map(({ term }) => term));
-const ACCEPTED = new Set(["being", "affiliation"]);
 
 /** Validate a being's map of defining relationships. */
 export function checkSocialTies(note, { index } = {}) {
@@ -38,6 +37,7 @@ export function checkSocialTies(note, { index } = {}) {
             },
         ];
     const findings = [];
+    const seen = new Map();
     for (const [key, term] of Object.entries(ties)) {
         const tuple = parseAddress(
             key,
@@ -54,25 +54,36 @@ export function checkSocialTies(note, { index } = {}) {
                 ...at(key),
                 message: `data.socialTies key ${JSON.stringify(key)} is not a complete Address (${tuple.reason}); write being or affiliation as its type`,
             });
-        } else if (!ACCEPTED.has(tuple.type)) {
+        } else if (!acceptsType(tuple, SOCIAL_TIE_TARGET_TYPES)) {
             findings.push({
                 ...at(key),
                 message: `data.socialTies accepts being or affiliation, not ${tuple.type}`,
             });
-        } else if (
-            tuple.package === (index?.contentPackage ?? note.fm?.package) &&
-            tuple.type === "being" &&
-            tuple.shortcode === note.fm?.shortcode
-        ) {
-            findings.push({
-                ...at(key),
-                message: `data.socialTies cannot address this being itself`,
-            });
-        } else if (index?.addressHit && !index.addressHit(renderAddress(tuple))) {
-            findings.push({
-                ...at(key),
-                message: `data.socialTies target ${renderAddress(tuple)} does not resolve`,
-            });
+        } else {
+            const target = renderAddress(tuple);
+            if (seen.has(target)) {
+                findings.push({
+                    ...at(key),
+                    message: `data.socialTies names the same target ${target} as ${JSON.stringify(seen.get(target))}; keep one tie per target`,
+                });
+            } else {
+                seen.set(target, key);
+            }
+            if (
+                tuple.package === (index?.contentPackage ?? note.fm?.package) &&
+                tuple.type === "being" &&
+                tuple.shortcode === note.fm?.shortcode
+            ) {
+                findings.push({
+                    ...at(key),
+                    message: `data.socialTies cannot address this being itself`,
+                });
+            } else if (index?.addressHit && !index.addressHit(target)) {
+                findings.push({
+                    ...at(key),
+                    message: `data.socialTies target ${target} does not resolve`,
+                });
+            }
         }
         if (!TERMS.has(term))
             findings.push({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.14.3",
+    "version": "22.15.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -134,6 +134,8 @@
     "dependencies": {
         "@duckdb/node-api": "^1.5.5-r.4",
         "@foundryvtt/foundryvtt-cli": "^3.0.4",
+        "@resvg/resvg-js": "^2.6.2",
+        "@viz-js/viz": "^3.30.0",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
         "classic-level": "^3.0.0",

package/types/engine/being-age.d.mts

@@ -21,7 +21,7 @@ export function parseAgeMagnitude(raw: unknown): {
  * @returns {number|null} The age, or `null` where `born` is `unknown` or
  *   absent, where no present is declared, or where either date fails to parse.
  */
-export function computeAge(bornRaw: unknown, presentRaw: unknown): number | null;
+export function computeAge(bornRaw: unknown, presentRaw: unknown, dateContext?: {}): number | null;
 /**
  * Fill in a being's computed `age`, and the numeric companion an estimate
  * carries beside it — mutating the frontmatter object handed in, never a file
@@ -39,7 +39,7 @@ export function computeAge(bornRaw: unknown, presentRaw: unknown): number | null
  *   `undefined`/`null` where it states none.
  * @returns {void}
  */
-export function applyComputedBeingAge(fm: object, presentRaw: unknown): void;
+export function applyComputedBeingAge(fm: object, presentRaw: unknown, dateContext?: {}): void;
 /**
  * A being's `data.present`, read from every `place` note a batch of records or
  * frontmatter objects carries.

package/types/engine/calendar-artifacts.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Emit calendar definitions and import envelopes from the package's index.
+ *
+ * @param {object} opts
+ * @param {object} opts.config - Resolved content configuration.
+ * @param {string} opts.calendariaVersion - Version whose import format is targeted.
+ * @returns {{directory: string, calendars: number, files: number}}
+ */
+export function emitCalendarArtifacts({ config, calendariaVersion }?: {
+    config: object;
+    calendariaVersion: string;
+}): {
+    directory: string;
+    calendars: number;
+    files: number;
+};

package/types/engine/calendar-notes.d.mts

@@ -103,7 +103,7 @@ export function quarterDays(daysPerYear: number): number[];
  *   its own package.
  * @returns {object} The definition.
  */
-export function compileCalendar({ note, invariants, contentPackage }: {
+export function compileCalendar({ note, invariants, contentPackage, dateContext }: {
     note: object;
     invariants: object;
     contentPackage?: string | undefined;

package/types/engine/calendars.d.mts

@@ -35,6 +35,60 @@ export function canonicalYear(year: number, epoch?: number): number;
  * @returns {number} The sort key.
  */
 export function dateSortKey(year: number, month: number | null, day: number | null): number;
+/**
+ * Days from an arbitrary canonical origin to a canonical year and day.
+ *
+ * Canonical years form a continuous integer line. Day one opens each year;
+ * calendar month divisions play no part in this count.
+ *
+ * @param {number} year - Canonical year.
+ * @param {number} day - Day of that year, starting at one.
+ * @param {number} originYear - Canonical year whose first day is offset zero.
+ * @param {number} daysPerYear - The world's authored year length.
+ * @returns {number} Signed whole-day offset.
+ */
+export function canonicalDayOffset(year: number, day: number, originYear: number, daysPerYear: number): number;
+/**
+ * The canonical year and day at a signed offset from an arbitrary origin.
+ * Flooring the division keeps the day within the year before the origin.
+ *
+ * @param {number} offset - Whole days from the origin.
+ * @param {number} originYear - Canonical year whose first day is offset zero.
+ * @param {number} daysPerYear - The world's authored year length.
+ * @returns {{year: number, day: number}} Canonical year and day.
+ */
+export function canonicalDateFromOffset(offset: number, originYear: number, daysPerYear: number): {
+    year: number;
+    day: number;
+};
+/**
+ * Print a calendar-neutral date as `<year>.<day>[:HHMMSS]`.
+ *
+ * @param {{year: number, day: number, seconds?: number}} date - Canonical date.
+ * @param {number} daysPerYear - The world's authored year length.
+ * @returns {string} The canonical spelling.
+ */
+export function formatCanonicalDate(date: {
+    year: number;
+    day: number;
+    seconds?: number;
+}, daysPerYear: number): string;
+/**
+ * Read the calendar-neutral `<year>.<day>[:HHMMSS]` spelling.
+ *
+ * This is distinct from an authored month date such as `720/6`; no calendar
+ * month list is consulted to read a canonical day of year.
+ *
+ * @param {unknown} value - Canonical date text.
+ * @param {number} daysPerYear - The world's authored year length.
+ * @returns {{year: number, day: number, seconds?: number}|null} The date, or
+ *   `null` when the spelling or a component is invalid.
+ */
+export function parseCanonicalDate(value: unknown, daysPerYear: number): {
+    year: number;
+    day: number;
+    seconds?: number;
+} | null;
 /**
  * One month of a calendar, as the note declares it.
  *
@@ -101,6 +155,17 @@ export function monthStarts(months: readonly CalendarMonth[]): number[];
  * @returns {number} The day of the year.
  */
 export function dayOfYear(months: readonly CalendarMonth[], month: number, day: number): number;
+/**
+ * Recover a calendar's month and day from an ordinal day of its year.
+ *
+ * @param {readonly CalendarMonth[]} months - The ordered month list.
+ * @param {number} ordinal - Day of year, starting at one.
+ * @returns {{month: number, day: number}|null} The named day, or `null` outside the year.
+ */
+export function monthDayOfYear(months: readonly CalendarMonth[], ordinal: number): {
+    month: number;
+    day: number;
+} | null;
 /**
  * How far into its cycle a moon is on a given day.
  *

package/types/engine/content-images.d.mts

@@ -32,12 +32,13 @@ export function parseImageDirective(raw?: string): {
 /**
  * The classes a figure carries, from a parsed directive.
  *
- * @param {{classes?: string[], float?: string}} [directive] - As parsed.
+ * @param {{classes?: string[], size?: string, float?: string}} [directive] - As parsed.
  * @returns {string} A space-separated class list, always naming
  *   {@link IMAGE_FIGURE_CLASS} first.
  */
-export function figureClasses({ classes, float }?: {
+export function figureClasses({ classes, size, float }?: {
     classes?: string[];
+    size?: string;
     float?: string;
 }): string;
 /**
@@ -58,13 +59,15 @@ export function escapeHtml(text: string): string;
  * @param {string} image.src - The address, resolved for the surface.
  * @param {string} [image.alt] - The alt text, which is also the caption.
  * @param {string[]} [image.classes] - Width classes, from the directive.
+ * @param {string} [image.size] - Named display size, from the directive.
  * @param {string} [image.float] - The float position, from the directive.
  * @returns {string} The figure, as one HTML block.
  */
-export function imageFigureHtml({ src, alt, classes, float }: {
+export function imageFigureHtml({ src, alt, classes, size, float }: {
     src: string;
     alt?: string | undefined;
     classes?: string[] | undefined;
+    size?: string | undefined;
     float?: string | undefined;
 }): string;
 /**
@@ -249,7 +252,7 @@ export const IMAGE_CLASSES: Readonly<Record<string, {
     scope: string;
     describe: string;
 }>>;
-/** The named sizes an image directive accepts without applying a display size. */
+/** The named sizes an image directive accepts. */
 export const IMAGE_SIZES: readonly string[];
 /**
  * The `float:` positions an image may take, and where each puts it.

package/types/engine/exported-scene.d.mts

@@ -0,0 +1,12 @@
+/**
+ * Compile a Foundry Scene export into a pack document.
+ *
+ * Only the note-derived Scene ID, compendium metadata, and pins marked
+ * `#anchor` change. Every other authored Scene field passes through.
+ *
+ * @param {object} fm - The map note's frontmatter.
+ * @param {string} markdown - Its converted Markdown body.
+ * @param {object} [opts] - Pack metadata, derived JournalEntry ID, and asset resolver.
+ * @returns {object} The keyed Scene document.
+ */
+export function buildExportedScene(fm: object, markdown: string, { journalEntryId, stats, resolveAddress }?: object): object;

package/types/engine/index.d.mts

@@ -31,7 +31,9 @@ export * as siteMaps from "./site-maps.mjs";
 export * as systems from "./systems.mjs";
 export * as calendars from "./calendars.mjs";
 export * as noteDates from "./note-dates.mjs";
+export * as reckoningMarkers from "./reckoning-markers.mjs";
 export * as calendarNotes from "./calendar-notes.mjs";
+export * as calendarArtifacts from "./calendar-artifacts.mjs";
 export * as beingAge from "./being-age.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";

package/types/engine/itinerary-scenes.d.mts

@@ -0,0 +1,29 @@
+/** GraphViz's plain coordinates, converted to pixel positions on its PNG. */
+export function pinPositions(plain: any, width: any, height: any): Map<any, any>;
+/**
+ * Emit backgrounds into the staged package and return Scenes and the journals
+ * their pins need. The caller writes them into its Scene and Adventure packs.
+ */
+export function buildItineraryScenes({ config, records, contentBase, journalSourceDirs, stats, foreign, }: {
+    config: any;
+    records: any;
+    contentBase: any;
+    journalSourceDirs?: never[] | undefined;
+    stats: any;
+    foreign?: {
+        index: Map<string, object>;
+        packages: Set<string>;
+        stale: Array<{
+            package: string;
+            reason: string;
+        }>;
+    } | undefined;
+}): {
+    scenes: object[];
+    journal: any[];
+    findings: {
+        file: any;
+        severity: string;
+        message: string;
+    }[];
+};

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

@@ -30,19 +30,13 @@ export function relatedPlaces(places: Map<string, import("./map-places.mjs").Map
  * @param {number} [opts.ranksep] - The tree's `ranksep`, inches.
  * @param {number} [opts.scale=1] - Multiplies every node's size and font.
  * @param {boolean} [opts.polities=true] - Whether the tree draws polities.
- * @param {(engine: string) => string|undefined} [opts.locate] - How a GraphViz
- *   engine's binary is found; the real lookup by default.
- * @param {boolean} [opts.requireGraphviz=true] - Whether a missing engine is
- *   an error. False, the `.dot` files are written, the renderings skipped,
- *   and one warning returned.
  * @returns {{written: string[], findings: Array<{file: string, line?: number,
- *   column?: number, severity: "error"|"warning", message: string}>,
- *   skipped: boolean}} What was written, what was found, and whether the
- *   rendering was skipped for want of GraphViz.
+ *   column?: number, severity: "error"|"warning", message: string}>}} What was
+ *   written and what was found.
  * @throws {Error} When no mode is asked for, a named place is not one, the
- *   horizon is not a marker of the scale, or GraphViz is required and absent.
+ *   horizon is not a marker of the scale.
  */
-export function buildMaps({ world, outDir, tree, root, from, chart, horizon, travel, engine, rankdir, nodesep, ranksep, scale, polities, locate, requireGraphviz, }: {
+export function buildMaps({ world, outDir, tree, root, from, chart, horizon, travel, engine, rankdir, nodesep, ranksep, scale, polities, }: {
     world: import("./map-places.mjs").MapWorld;
     outDir: string;
     tree?: boolean | undefined;
@@ -57,8 +51,6 @@ export function buildMaps({ world, outDir, tree, root, from, chart, horizon, tra
     ranksep?: number | undefined;
     scale?: number | undefined;
     polities?: boolean | undefined;
-    locate?: ((engine: string) => string | undefined) | undefined;
-    requireGraphviz?: boolean | undefined;
 }): {
     written: string[];
     findings: Array<{
@@ -68,7 +60,6 @@ export function buildMaps({ world, outDir, tree, root, from, chart, horizon, tra
         severity: "error" | "warning";
         message: string;
     }>;
-    skipped: boolean;
 };
 /**
  * The directory the maps land in, below a package's root.

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

@@ -1,68 +1,26 @@
 /**
- * Find a GraphViz engine's binary.
+ * Render a DOT source file to SVG, plain positions, or a PNG background.
  *
- * `PATH` first, then the directories a package manager installs into, so a
- * shell whose profile does not export Homebrew's directory still finds it.
- * The result is a path to a file that exists; whether it runs is the render's
- * business.
+ * A PNG uses the same Graphviz SVG layout as the vector map. SVG dimensions
+ * are in points; resvg starts at 96 pixels per inch, so the zoom converts
+ * the requested DPI to the same physical size as Graphviz's PNG output.
  *
- * @param {string} engine - One of {@link GRAPHVIZ_ENGINES}.
- * @param {object} [opts]
- * @param {Record<string, string|undefined>} [opts.env] - The environment to
- *   read `PATH` from, defaulting to the process's.
- * @param {readonly string[]} [opts.fallbacks] - The directories tried after
- *   `PATH`, defaulting to the package managers' ones.
- * @returns {string|undefined} The binary, or `undefined` when none is found.
- * @throws {Error} When `engine` is not a GraphViz engine this command uses.
- */
-export function findGraphviz(engine: string, { env, fallbacks }?: {
-    env?: Record<string, string | undefined> | undefined;
-    fallbacks?: readonly string[] | undefined;
-}): string | undefined;
-/**
- * What to say when an engine is not installed: the name, and what installs
- * it.
- *
- * @param {string} engine - The engine that was wanted.
- * @returns {string} The message.
- */
-export function graphvizMissingMessage(engine: string): string;
-/**
- * Render a `.dot` file with a GraphViz engine.
- *
- * The engine is run over the file rather than fed the text, so the file the
- * command keeps is exactly what was drawn. Warnings GraphViz prints — an
- * unknown font, an overlapping label — are returned rather than swallowed,
- * and a non-zero exit is an error naming the file.
- *
- * @param {string} dotPath - The `.dot` file.
- * @param {string} outPath - Where to write the rendering.
+ * @param {string} dotPath - The saved DOT source.
+ * @param {string} outPath - The output file.
  * @param {object} opts
- * @param {string} opts.binary - The engine's binary, from {@link findGraphviz}.
- * @param {string} [opts.format="svg"] - The `-T` format.
- * @param {string[]} [opts.args] - Further arguments, before the file.
- * @returns {{warnings: string}} What the engine printed on stderr.
- * @throws {Error} When the engine exits non-zero or cannot be run.
+ * @param {"dot"|"twopi"|"neato"} opts.engine - Layout engine.
+ * @param {"svg"|"plain"|"png"} [opts.format="svg"] - Output format.
+ * @param {2} [opts.nop] - Preserve positioned nodes as `neato -n2` does.
+ * @param {number} [opts.dpi=96] - PNG resolution.
+ * @returns {{warnings: string}} Renderer warnings.
  */
-export function renderDot(dotPath: string, outPath: string, { binary, format, args }: {
-    binary: string;
-    format?: string | undefined;
-    args?: string[] | undefined;
+export function renderDot(dotPath: string, outPath: string, { engine, format, nop, dpi }: {
+    engine: "dot" | "twopi" | "neato";
+    format?: "svg" | "plain" | "png" | undefined;
+    nop?: 2 | undefined;
+    dpi?: number | undefined;
 }): {
     warnings: string;
 };
-/**
- * The layout engines the map command may ask for. `dot` draws a tree by
- * rank, `twopi` the same tree radially, `neato` a graph by its edge lengths —
- * and, with every node pinned, the map from a place.
- *
- * @type {readonly string[]}
- */
+/** The layout engines accepted by the map command. */
 export const GRAPHVIZ_ENGINES: readonly string[];
-/**
- * What installs GraphViz on the two platforms a contributor is likely to be
- * on, as the clause every "not installed" message ends with.
- *
- * @type {string}
- */
-export const GRAPHVIZ_INSTALL: string;

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

@@ -214,9 +214,13 @@ export type MapWorld = {
  */
 export type Containment = {
     /**
-     * - The one `subType: world` place.
+     * - The world when exactly one is present.
      */
     world: string | undefined;
+    /**
+     * - Every `subType: world` place, sorted.
+     */
+    worlds: string[];
     /**
      * - Regions parented directly on the world,
      * in name order.

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

@@ -0,0 +1,8 @@
+/** Rasterize an authored SVG map into the staged Foundry package. */
+export function rasterizeMapSvg({ foundryPath, width, height, sceneId, config }: {
+    foundryPath: any;
+    width: any;
+    height: any;
+    sceneId: any;
+    config: any;
+}): string;