@heroiclands/package-build 25.6.2 → 25.7.0

package/content-config.mjs

@@ -228,6 +228,93 @@ export function siteBase(config) {
     return config.site.base || `/${config.contentPackage}/`;
 }
 
+/**
+ * Apply validated runtime site URLs to a resolved configuration, without changing it.
+ * The caller checks the authored homepage before applying these build options.
+ *
+ * @param {ContentBuildConfig} config - The resolved authored configuration.
+ * @param {object} options - Runtime options.
+ * @param {string} [options.root] - Domain from which www and CDN origins derive.
+ *   Defaults to internal.heroiclands.org; explicit root replaces configured assets.
+ * @param {string} [options.baseUrl] - Absolute HTTP(S) site URL ending in `/`;
+ *   overrides the root-derived site URL.
+ * @param {string} [options.assets] - Absolute HTTP(S) asset root; overrides both
+ *   root-derived and configured assets.
+ * @returns {ContentBuildConfig} The effective configuration, frozen. Its homepage
+ *   and site.assets are the selected inputs for downstream site integrations.
+ */
+export function siteBuildConfig(config, { root, baseUrl, assets } = {}) {
+    const domain = root ?? "internal.heroiclands.org";
+    if (
+        typeof domain !== "string" ||
+        domain.length > 253 ||
+        !domain.includes(".") ||
+        !domain.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label))
+    ) {
+        throw new TypeError("--root must be a domain without a scheme, path, port or credentials");
+    }
+    const homepage =
+        baseUrl === undefined ?
+            `https://www.${domain.toLowerCase()}${new URL(config.homepage).pathname}`
+        :   buildUrl(baseUrl, "--base-url").href;
+    const base = normalizeSiteBase(new URL(homepage).pathname);
+    const assetRoot =
+        assets !== undefined ? normalizeSiteAssets(buildUrl(assets, "--assets").href)
+        : root !== undefined ? `https://cdn.${domain.toLowerCase()}`
+        : config.site.assets || `https://cdn.${domain.toLowerCase()}`;
+    checkSiteSitemaps(config.site.sitemaps, base, config.contentPackage);
+    return Object.freeze({
+        ...config,
+        homepage,
+        site: Object.freeze({ ...config.site, base, assets: assetRoot }),
+    });
+}
+
+/**
+ * A runtime web root must survive URL joining and mapping to a local directory.
+ *
+ * @param {string} value - The command-line value.
+ * @param {string} option - The option naming it.
+ * @returns {URL} The checked URL.
+ */
+function buildUrl(value, option) {
+    // URL parsing consumes both literal and escaped dot segments.
+    const rawPath = /^https?:\/\/[^/?#]+([^?#]*)/i.exec(value)?.[1] ?? "";
+    if (
+        rawPath.includes("%") ||
+        rawPath.split("/").some((segment) => segment === "." || segment === "..")
+    ) {
+        throw new TypeError(
+            `${option} must use a plain path without percent escapes or dot segments`,
+        );
+    }
+    let url;
+    try {
+        url = new URL(value);
+    } catch {
+        throw new TypeError(`${option} must be an absolute HTTP(S) URL`);
+    }
+    if (
+        !/^https?:\/\/[^/]+/i.test(value) ||
+        /[\s\\]/.test(value) ||
+        !["http:", "https:"].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        value.includes("?") ||
+        value.includes("#") ||
+        url.pathname.includes("//") ||
+        url.pathname.includes("%")
+    ) {
+        throw new TypeError(
+            `${option} must be an absolute HTTP(S) URL with a plain path and no credentials, query or fragment`,
+        );
+    }
+    if (option === "--base-url" && !url.pathname.endsWith("/")) {
+        throw new TypeError(`${option} must end with /`);
+    }
+    return url;
+}
+
 /**
  * Whether this package publishes the pages its content tree compiles to.
  *
@@ -625,6 +712,8 @@ export function publishesContentPages(config) {
  *                                          `pack:` frontmatter, and one pack of
  *                                          the type is marked `default: true` to
  *                                          receive the notes that name none.
+ * @property {Record<string, any> & {inputs?: string}} [site] Site settings;
+ *                                          inputs names the optional local input provider.
  * @property {PathsInput} [paths]           Layout overrides. See {@link DEFAULT_PATHS}.
  * @property {string[]} [skipDirectories]   Directory names the content walk ignores
  *                                          wherever they appear (e.g. Obsidian's
@@ -680,6 +769,8 @@ export function publishesContentPages(config) {
  *                                     which Foundry serves no files for. See
  *                                     {@link module:engine/helpers.resolveImg},
  *                                     the one reader of it.
+ * @property {Readonly<Record<string, any> & {inputs: string}>} site Frozen site settings;
+ *                                     inputs is the local provider path or an empty string.
  * @property {Readonly<ResolvedPaths>} paths
  * @property {Readonly<StatsSpec>|null} stats  `null` for a `documentation`
  *                                     package, which stamps no `_stats`.
@@ -785,6 +876,7 @@ const SITE_KEYS = [
     "tags",
     "sitemaps",
     "mergeIndexes",
+    "inputs",
 ];
 const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
 const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
@@ -1874,6 +1966,23 @@ function packageSiteList(value, field, contentPackage) {
     );
 }
 
+/**
+ * @param {readonly string[]} sitemaps - The configured package sitemaps.
+ * @param {string} base - The site path.
+ * @param {string} contentPackage - The package id.
+ * @returns {void}
+ */
+function checkSiteSitemaps(sitemaps, base, contentPackage) {
+    if (sitemaps.length && base !== "/") {
+        fail(
+            "site.sitemaps",
+            "names the package sites a sitemap index lists, and a sitemap index and " +
+                "`robots.txt` belong at the root of an origin; this site is served at " +
+                `\`${base || `/${contentPackage}/`}\`, so declare \`site.base: /\` or drop the key`,
+        );
+    }
+}
+
 /**
  * The `site` section — how this repository frames the website it publishes.
  *
@@ -1922,6 +2031,7 @@ function normalizeSite(value, contentPackage) {
         tags: false,
         sitemaps: Object.freeze([]),
         mergeIndexes: Object.freeze([]),
+        inputs: "",
     });
     if (value === undefined) return empty;
     if (!isPlainObject(value)) fail("site", "must be a mapping");
@@ -1939,14 +2049,7 @@ function normalizeSite(value, contentPackage) {
     const base = normalizeSiteBase(input.base);
     const search = optionalBoolean(input.search, "site.search", true);
     const sitemaps = packageSiteList(input.sitemaps, "site.sitemaps", contentPackage);
-    if (sitemaps.length && base !== "/") {
-        fail(
-            "site.sitemaps",
-            "names the package sites a sitemap index lists, and a sitemap index and " +
-                "`robots.txt` belong at the root of an origin; this site is served at " +
-                `\`${base || `/${contentPackage}/`}\`, so declare \`site.base: /\` or drop the key`,
-        );
-    }
+    checkSiteSitemaps(sitemaps, base, contentPackage);
     const mergeIndexes = packageSiteList(input.mergeIndexes, "site.mergeIndexes", contentPackage);
     if (mergeIndexes.length && !search) {
         fail(
@@ -1956,6 +2059,12 @@ function normalizeSite(value, contentPackage) {
         );
     }
 
+    const inputs =
+        input.inputs === undefined ? "" : requireNonEmptyString(input.inputs, "site.inputs");
+    if (inputs && !inputs.split("/").every((segment) => /^[a-z0-9][a-z0-9._-]*$/i.test(segment))) {
+        fail("site.inputs", "must be a plain relative module path without dot segments");
+    }
+
     return Object.freeze({
         base,
         title: input.title === undefined ? "" : requireNonEmptyString(input.title, "site.title"),
@@ -1978,6 +2087,7 @@ function normalizeSite(value, contentPackage) {
         tags: optionalBoolean(input.tags, "site.tags", false),
         sitemaps,
         mergeIndexes,
+        inputs,
     });
 }
 

package/docs/api.md

@@ -193,16 +193,18 @@ Whether a content tree has anything to compile. The pack build's worst failure i
 
 The consuming repository's resolved `package-build.config.yaml`: the content package, the Foundry package and its kind, every path, the `_stats` identity, item-type membership and the pack list — read on call rather than hoisted at import, so importing this package never requires a configuration to exist.
 
-| Export              | Signature                            | Returns                       | Use it when                                                                          |
-| ------------------- | ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------ |
-| `CONFIG_BASENAME`   | `const CONFIG_BASENAME`              | —                             | naming the stem every consuming repository declares its build under                  |
-| `CONFIG_FILENAMES`  | `const CONFIG_FILENAMES`             | —                             | listing the file names a configuration may be written as                             |
-| `findConfigFile`    | `findConfigFile(from)`               | `string \| undefined`         | finding the nearest configuration file at or above a directory                       |
-| `resolveConfigFile` | `resolveConfigFile(...)`             | `{path, fromCwd, fromModule}` | asking which configuration file a build launched here would read, without loading it |
-| `locateConfigError` | `locateConfigError(err, configPath)` | the decorated error           | attaching the position of the key a configuration error names                        |
-| `configFromData`    | `configFromData(data, configPath)`   | `ContentBuildConfig`          | turning a parsed YAML configuration into the frozen one the engine reads             |
-| `loadPackConfig`    | `loadPackConfig()`                   | `ContentBuildConfig`          | reading the consuming repository's resolved, frozen configuration                    |
-| `packConfigPath`    | `packConfigPath()`                   | `string`                      | naming the file `loadPackConfig` resolved the configuration from, for a diagnostic   |
+| Export              | Signature                            | Returns                       | Use it when                                                                                      |
+| ------------------- | ------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `CONFIG_BASENAME`   | `const CONFIG_BASENAME`              | —                             | naming the stem every consuming repository declares its build under                              |
+| `CONFIG_FILENAMES`  | `const CONFIG_FILENAMES`             | —                             | listing the file names a configuration may be written as                                         |
+| `findConfigFile`    | `findConfigFile(from)`               | `string \| undefined`         | finding the nearest configuration file at or above a directory                                   |
+| `resolveConfigFile` | `resolveConfigFile(...)`             | `{path, fromCwd, fromModule}` | asking which configuration file a build launched here would read, without loading it             |
+| `locateConfigError` | `locateConfigError(err, configPath)` | the decorated error           | attaching the position of the key a configuration error names                                    |
+| `configFromData`    | `configFromData(data, configPath)`   | `ContentBuildConfig`          | turning a parsed YAML configuration into the frozen one the engine reads                         |
+| `loadPackConfig`    | `loadPackConfig()`                   | `ContentBuildConfig`          | reading the consuming repository's resolved, frozen configuration                                |
+| `packConfigPath`    | `packConfigPath()`                   | `string`                      | naming the file `loadPackConfig` resolved the configuration from, for a diagnostic               |
+| `readPackConfig`    | `readPackConfig(configPath)`         | `ContentBuildConfig`          | reading the configuration one named file declares, unmemoised                                    |
+| `withPackConfig`    | `withPackConfig(config, fn, file?)`  | what `fn` returns             | running work, asynchronous included, with `config` as the configuration `loadPackConfig` answers |
 
 ### `engine.packRouter`
 
@@ -621,12 +623,11 @@ The npm-installed Graphviz runtime draws SVG maps. The `.dot` source stays besid
 
 The map from each place, drawn for the site: `package-build site build` draws the map from every place of this package given a **From here** section — with the site's base, so every name links through it — and sets each drawing inline in that section, where its place names stay links. `site.maps: false` gives no place the section, and nothing is drawn.
 
-| 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 })` | `{maps, findings}` | drawing the map from every place given a **From here** section, keyed by the file name the section names        |
-| `inlineDrawingFigure` | `inlineDrawingFigure(svg, alt)`                         | `string`           | the one HTML block the website sets an inline drawing in, with no blank line to end it early                    |
+| 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, only?, outDir? })` | `{maps, findings}` | drawing the map from every place given a **From here** section, keyed by the file name the section names        |
 
 ### `engine.systems`
 
@@ -1277,6 +1278,36 @@ The deployed layout of a package's pictures, and which of them ship. A Foundry p
 | `stagePackageAssets`      | `stagePackageAssets({ assetsBase, contentPackage, stageDir, title, transform, shippingLicenses })` | `{staged, excluded, findings, manifest}`                                        | staging a package's shipped pictures flat and writing `asset-sets/default.json`; nothing is staged when `findings` is non-empty |
 | `rowsStagingPictureRoots` | `rowsStagingPictureRoots(rows, { rootDir, assetsBase })`                                           | `{index, from, root}[]`                                                         | finding `packageBuild.assets` rows that would copy a picture root around the filter                                             |
 
+### CDN publication transports
+
+Import `@heroiclands/package-build/engine/cdn-publish` directly. `planCdnPublish`
+collects the same asset records and shipping selection as staging, applies the
+provided transform, and builds destination-relative keys plus a named set whose
+sources use its `host` argument. It does not upload anything.
+
+`publishToCdn(plan, { store, dryRun, log })` accepts a destination-independent
+store with async `size(key)`, `read(key)`, optional `write(key, body, contentType)`
+and a safe `describe` string. It validates every planned relative key before
+reading or writing, skips pictures by size, compares set bytes, and withholds the
+set after a picture failure. `dryRun` never calls `write`.
+
+`internalStore({ destination, fetch, transfer })` combines public HTTPS reads at
+`INTERNAL_CDN_HOST` with rsync writes, defaulting to `INTERNAL_CDN_DESTINATION`
+(`atlas:/srv/preview/cdn`). An explicit SSH alias may target `alias:cdn` for the
+forced-rrsync receiver. Writes stage only the supplied bytes in temporary regular
+files, invoke rsync without deletion, and clean up after success or failure.
+`fetch` and `transfer(args)` can be supplied for isolated tests; the default
+transfer executes rsync with batch SSH and strict host-key checking.
+
+`s3Store(credentials)` retains signed S3/R2 requests. `publicStore(host, fetch)`
+provides read-only HTTP comparisons. `CANONICAL_CDN_ORIGIN`, exported from
+`engine/site-config`, names the owned public CDN origin used by pathname
+projection. Its single definition lives in the leaf `engine/site-origins` module
+to avoid a cycle through site configuration and content rendering.
+The CLI owns environment loading and
+`--dest` selection; site builds never call a publisher. See
+[CDN publication](commands.md#package-build-cdn-publish) for operator access.
+
 ### `engine.assetReferences`
 
 Every asset reference in a compiled document states the asset's address: an `<img>` carries `data-asset`, and a path field's address sits in `flags.<system>.assets` on the document holding it, nested to mirror the field's path. A reference to a picture its package does not ship compiles to that package's stand-in and keeps the excluded address.
@@ -1357,6 +1388,16 @@ configuration and incremental render state stay in the calling thread. Every
 update is prepared in a separate output tree, then installed between HTTP
 requests so readers receive complete files.
 
+`buildPackageSite` invokes configured `site.inputs` before content work. The
+module's default export has the `SiteInputsProvider` contract:
+`({config}) => {navigation, files}` or a promise of that object. It receives the
+immutable effective configuration; `navigation` uses `NavigationEntry[]`, and
+`files` is `Record<string, string>` of relative output paths to UTF-8 text.
+Provider files are validated against unsafe paths, symlinks and builder-owned
+output before output replacement, written after the renderer's clearing step,
+and recorded in `written.files`. Without a provider, cached navigation remains
+required. See [local site inputs](configuration.md#local-site-inputs).
+
 ### `engine.contentRender`
 
 `createRenderer(target, options?)` builds the one markdown-it configuration every target renders through. `target` is `"foundry"`, `"web"`, `"preview"` or `"book"`. The renderer holds the configured parser (`md`), the names of the plugins installed (`plugins`), and three functions: `prepare` writes the constructs markdown-it has no syntax for — marked text, captioned items, named blocks, verse and alerts — as HTML between blank lines; `render` prepares and renders to HTML; `renderInline` renders one inline run. The `book` target parses only, and its Typst stage reads the tokens.
@@ -1407,9 +1448,17 @@ locate it in the complete source. LF and CRLF retain their authored lengths.
 
 `previewIndex({ config, records, foreign? })` builds what [`renderPreview`](#enginesitepreview) takes as `index`: the link index, the asset address space, the languages' maps, the icon registry and an `expand` function that resolves a buffer's links, embeds, expressions and figure numbers as the website does. `records` are the content index's records and `foreign` the dependencies' indexes. Build it once per index and reuse it for every render.
 
-| Export         | Signature                                    | Returns                                | Use it when                                                              |
-| -------------- | -------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
-| `previewIndex` | `previewIndex({ config, records, foreign })` | `{ runs, icons, lookupAsset, expand }` | An editor holds a content index and wants the preview to render with it. |
+| Export              | Signature                                         | Returns                                | Use it when                                                               |
+| ------------------- | ------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
+| `previewIndex`      | `previewIndex({ config, records, foreign })`      | `{ runs, icons, lookupAsset, expand }` | An editor holds a content index and wants the preview to render with it.  |
+| `recordSiteContext` | `recordSiteContext({ config, records, foreign })` | `{ site, assets, events, runs }`       | Resolving a page against content-index records instead of a content tree. |
+
+`recordSiteContext` places every note that publishes a page at the URL the
+site gives it: the homepage at the package root, a note `site.sections` names
+at its section, and every other note at its address. `anchorsOf(record)` may
+answer a note's anchors as its page emits them, generated sections included;
+answering nothing keeps the record's own. `pages` maps each page's URL to its
+record.
 
 ### `engine.sitePreview`
 
@@ -1589,16 +1638,16 @@ A list item opened with `[ ]` or `[x]`, reported. The format has no checkbox: a
 
 One authored pathname, and the four addresses it resolves to. A note names a file once — in `img:`, in `data.portrait:`, in the body of a markdown image — and the first segment says which package owns it when an `assets/` follows. Every surface derives its own address from that one statement: the path inside a Foundry install, the file in the owning repository's tree, the address the website serves, and where the book stages its copy.
 
-| Export                  | Signature                                     | Returns                                                                                            | Use it when                                                                                                          |
-| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `ASSETS_SEGMENT`        | `const ASSETS_SEGMENT`                        | —                                                                                                  | The directory a package ships its files in.                                                                          |
-| `PATHNAME_SURFACES`     | `const PATHNAME_SURFACES`                     | —                                                                                                  | The surfaces one authored pathname resolves for.                                                                     |
-| `pathnameProblem`       | `function pathnameProblem(raw)`               | {string} The problem, as a finding's sentence, or `""`.                                            | What is wrong with an authored pathname, or `""` when nothing is.                                                    |
-| `packageAddresses`      | `function packageAddresses(config)`           | {Map<string, {root: string\|null, id: string\|null, own: boolean}>} The packages, by package name. | Every content package this build can resolve a pathname against.                                                     |
-| `resolvePathname`       | `function resolvePathname(raw, config)`       | {PathnameForms\|null} The four forms, or `null` when the note names no file.                       | Resolve one authored pathname into the address each surface serves.                                                  |
-| `assetPathnameKey`      | `function assetPathnameKey(src, config)`      | {string\|null} The pathname, or `null` for an address naming no asset record to look up.           | The pathname one authored image address keys an asset's role and pixel size under, whichever form it was written in. |
-| `servesFoundry`         | `function servesFoundry(config)`              | {boolean} Whether the package being built has a Foundry root.                                      | Whether this build installs anything into a Foundry data directory.                                                  |
-| `foundryAddressProblem` | `function foundryAddressProblem(raw, config)` | {string} The problem, as a finding's sentence, or `""`.                                            | Why a pathname has no Foundry address, or `""` when it has one.                                                      |
+| Export                  | Signature                                     | Returns                                                                                            | Use it when                                                                                                                                           |
+| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ASSETS_SEGMENT`        | `const ASSETS_SEGMENT`                        | —                                                                                                  | The directory a package ships its files in.                                                                                                           |
+| `PATHNAME_SURFACES`     | `const PATHNAME_SURFACES`                     | —                                                                                                  | The surfaces one authored pathname resolves for.                                                                                                      |
+| `pathnameProblem`       | `function pathnameProblem(raw)`               | {string} The problem, as a finding's sentence, or `""`.                                            | What is wrong with an authored pathname, or `""` when nothing is.                                                                                     |
+| `packageAddresses`      | `function packageAddresses(config)`           | {Map<string, {root: string\|null, id: string\|null, own: boolean}>} The packages, by package name. | Every content package this build can resolve a pathname against.                                                                                      |
+| `resolvePathname`       | `function resolvePathname(raw, config)`       | {PathnameForms\|null} The four forms, or `null` when the note names no file.                       | Resolve one authored pathname into the address each surface serves; canonical Heroic Lands CDN assets use effective site.assets in the web form only. |
+| `assetPathnameKey`      | `function assetPathnameKey(src, config)`      | {string\|null} The pathname, or `null` for an address naming no asset record to look up.           | The pathname one authored image address keys an asset's role and pixel size under, whichever form it was written in.                                  |
+| `servesFoundry`         | `function servesFoundry(config)`              | {boolean} Whether the package being built has a Foundry root.                                      | Whether this build installs anything into a Foundry data directory.                                                                                   |
+| `foundryAddressProblem` | `function foundryAddressProblem(raw, config)` | {string} The problem, as a finding's sentence, or `""`.                                            | Why a pathname has no Foundry address, or `""` when it has one.                                                                                       |
 
 ### `engine.contentLinks`
 
@@ -1654,7 +1703,8 @@ Shared helpers for the pack compilers in `packages/package-build/`. The HeroicLa
 | `convertNoteWikilinks`    | `convertNoteWikilinks(body, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap })` | `{{markdown: string, unresolved: Array<object>}}`                                                                                                                                                                                         | Converts the wikilinks in one note's markdown, reporting any that have no target in the content tree.                                                                                                |
 | `expandNoteTables`        | `function expandNoteTables(body,`                                                                           | `{{markdown: string, lineMap: Array<{line: number, generated: boolean}>}}` The body with every table expanded, and where each emitted line came from — which is what lets a diagnostic about the expanded body name an authored position. | Expand prepared SQL tables in one note's markdown, before wikilinks are resolved — so a generated cell may itself be a wikilink.                                                                     |
 | `folderFilename`          | `function folderFilename(name, id)`                                                                         | —                                                                                                                                                                                                                                         | Builds a compendium-source filename for a folder JSON document: `folder_Name_id.json` with non-alphanumeric runs replaced by underscores.                                                            |
-| `walkMarkdownTree`        | `walkMarkdownTree(rootDir, { skipDirectories, sources, renderDescription })`                                | generator yielding `{frontmatter, body, description, raw, bodyLine?, bodyColumn?, file, absPath}`                                                                                                                                         | walking a content tree and reading every markdown file's frontmatter and body; `skipDirectories` is required rather than defaulted, so two callers cannot silently disagree about the corpus's scope |
+| `walkMarkdownTree`        | `walkMarkdownTree(rootDir, { skipDirectories, sources, renderDescription, parse })`                         | generator yielding `{frontmatter, body, description, raw, bodyLine?, bodyColumn?, file, absPath}`                                                                                                                                         | walking a content tree and reading every markdown file's frontmatter and body; `skipDirectories` is required rather than defaulted, so two callers cannot silently disagree about the corpus's scope |
+| `walkMarkdownFiles`       | `walkMarkdownFiles(rootDir, { skipDirectories })`                                                           | generator yielding each `.md` file's absolute path                                                                                                                                                                                        | listing the files `walkMarkdownTree` reads, in its order, without reading them                                                                                                                       |
 
 `buildContentLinkIndex` accepts `{ config?, records, sqlTables?, foreign? }`.
 `records` is the required, supplied content corpus. The optional prepared
@@ -1665,9 +1715,12 @@ so glossary word links resolve to their dictionary entries.
 `renderDescription` option defaults to true; false leaves `description` empty
 while retaining authored body and positions. `walkMarkdownTree` accepts a
 selected `sources` map in walk order and the same rendering option, also true
-by default. Index collection explicitly omits unused rendered descriptions.
-`indexRecordsFor` accepts that selected map, a `syntax` projection function
-and a captured `foreignIndex`. These adapters do not retain state globally.
+by default, and a `parse` function called as `parseMarkdownFile` is, for a
+caller answering from earlier parses. Index collection explicitly omits unused
+rendered descriptions. `indexRecordsFor` accepts that selected map, a `syntax`
+projection function, a captured `foreignIndex` and a `cache` of earlier
+parses and per-note records, the one [`./note-page`](#note-page) keeps. These
+adapters do not retain state globally.
 
 The physical wrappers `lintContentCharset`, `lintContentHtml`,
 `lintContentIcons`, `lintContentImages` and `lintContentTaskLists` accept an
@@ -2152,6 +2205,138 @@ Where HM3 records the template priority — one statement (`data.templatePriorit
 | `HM3_DEFAULT_ITEM_ART` | `const HM3_DEFAULT_ITEM_ART` | —                                 | reading the full map of default item artwork keyed by **note** type (not document subtype) for HM3 items |
 | `hm3DefaultItemArt`    | `hm3DefaultItemArt(type)`    | `string` — the default image path | getting the default art path for an HM3 item's note type, throwing when the type is unknown              |
 
+### `engine.sitePage`
+
+One content page, from its note to its body HTML. The site build renders every
+page through these functions, and [`./note-page`](#note-page) renders a single
+note through the same ones. Nothing here reads a file.
+
+| Export                      | Signature                                | Returns                                            | Use it when                                                                                  |
+| --------------------------- | ---------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `parseNote`                 | `parseNote(source, file, ctx)`           | `{fm, body, bodyLine} \| null`                     | reading a note's frontmatter and body from its text, addresses decoded                       |
+| `contentPage`               | `contentPage(note, ctx)`                 | `{page?, fmLinks, addressFinding?} \| null`        | deciding whether a note publishes a page, and building it                                    |
+| `inlineDrawingFigure`       | `inlineDrawingFigure(svg, alt)`          | `string`                                           | the one HTML block the website sets an inline drawing in, with no blank line to end it early |
+| `pageFrontmatter`           | `pageFrontmatter(page, options)`         | `object`                                           | the frontmatter a page publishes with                                                        |
+| `pageTitle`                 | `pageTitle(page)`                        | `string`                                           | the title a page publishes under                                                             |
+| `resolveArtFields`          | `resolveArtFields(data, webSrc, artSrc)` | `void`                                             | rewriting a page's artwork addresses into the URLs the website serves                        |
+| `isPlainObject`             | `isPlainObject(value)`                   | `boolean`                                          | asking whether a value is a mapping a field may be read from                                 |
+| `renderSitePage`            | `renderSitePage(page, options)`          | `{markdown, figures, data, resolved, …Errors}`     | expanding one page with the passes the site writer uses                                      |
+| `resolveSitePass`           | `resolveSitePass(name, options)`         | `{beforeLinks?: Function}`                         | resolving `site.pass` to its bundle                                                          |
+| `sitePageDecorator`         | `sitePageDecorator(config, index)`       | `Function`                                         | adding the site's infobox and being metadata to a page's frontmatter                         |
+| `siteBodyRenderer`          | `siteBodyRenderer(config)`               | `(markdown, {runs, figures}) => string`            | rendering an expanded page body to the HTML the site writer receives                         |
+| `pageDiagnostics`           | `pageDiagnostics(result, rawOf)`         | `Array<{file, line?, column?, severity, message}>` | turning a page render's findings into located diagnostics                                    |
+| `frontmatterLinkDiagnostic` | `frontmatterLinkDiagnostic(finding)`     | `{file, severity, message}`                        | reporting a wikilink authored in frontmatter                                                 |
+| `addressDiagnostic`         | `addressDiagnostic(finding)`             | `{file, severity, message}`                        | reporting a note whose page has no address                                                   |
+
+`renderSitePage` takes `drawing`, a function from the file name a generated
+**From here** section names to that drawing's SVG text, and sets the drawing
+inline when it answers. The site build answers with the maps it drew.
+
+## `./note-page`
+
+One note, rendered to the body HTML its site page carries, for a preview that
+reads like the published page: links as their labels and unresolved ones
+marked, `.name` spans in bold, query fences evaluated into tables, inline verse
+broken onto its lines and the generated sections a page carries.
+
+```js
+import { renderNoteFile } from "@heroiclands/package-build/note-page";
+
+const { html, styles, findings, cache } = await renderNoteFile("assets/content/Lore/Tides.md", {
+  root: "/path/to/repository",
+});
+```
+
+| Export           | Signature                                                 | Returns                                      | Use it when                                                   |
+| ---------------- | --------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------- |
+| `renderNoteFile` | `renderNoteFile(path, { root?, cache?, prepareTables? })` | `Promise<{ html, styles, findings, cache }>` | rendering a saved note of a repository as its site page shows |
+
+`path` is the note, relative to `root` or absolute; `root` is the repository
+or any directory inside it, the working directory by default. The note is read
+from disk, so what is rendered is what is saved. `renderNoteFile` loads the
+repository's `package-build.config.yaml` and its dependencies' fetched indexes,
+derives the content tree's index records as every build does, answers the
+note's own queries and generated sections over them as `package-build site
+build` does, and renders the note through the site build's own page render.
+The repository's configuration answers every read of the configuration made
+during the call, wherever the caller stands. Nothing has to be built first: no
+content index and no site.
+
+The page resolves against the notes it links as their own pages emit them.
+The note is rendered once to learn which of the package's pages it looks up,
+and those notes' query answers and generated sections are prepared beside its
+own, so a link to a generated section such as `#fromhere` resolves, and a
+cross-note `{{ref}}` finds the target's figures, numbered as its page numbers
+them. A place's **From here** drawing is drawn for that place alone, in a
+scratch directory under the system's temporary directory that is removed once
+the drawing is read, and set inline as the site sets it.
+
+**The cache.** The records and the note's answers are kept in
+`build/cache/note-page/` under the repository root, and reused while every
+input they were derived from is unchanged. Nothing is reused otherwise: each
+stored answer is keyed by a hash of its inputs, which are
+
+- package-build's version and the bytes of its own modules, the Node.js
+  version and the DuckDB version;
+- the configuration file's bytes and the resolved configuration;
+- the bytes of every fetched dependency index, and the installed
+  `@heroiclands/fonts` version and manifest;
+- every note's path and the hash of its text, and the package's asset records.
+
+The dependencies' indexes and the configuration are read between two
+readings of those inputs, which are read again after the records are derived
+and around preparing any query answers the store lacks. When any reading
+differs, something changed while it was read: nothing is stored, and the whole
+render is done again from the start, the configuration resolved and the note's
+place in the tree checked afresh, so a retry answers as a fresh call would and
+a store always holds what was derived from the bytes its key names. After
+three such attempts the call throws. The cache holds two stores, each
+replaced whole by renaming a complete file over it. `notes.v8` keeps each note's parse, keyed by its text, and the
+records derived from that note alone, keyed also by what the tree gives every
+note: the setting date and calendars, the addresses the notes declare and the
+asset records. `tree.v8` keeps the whole tree's records, keyed by every input,
+and beside them the query answers of each note a render has needed. So a second render of an
+unchanged tree reads the records and the answers; a changed note re-derives
+its own records and re-runs the passes that read the whole tree; a changed
+address, calendar, asset, dependency index, configuration or toolchain
+re-derives every note. A store that cannot be read, that was written for
+other inputs, or that holds an entry of the wrong shape, down to each table
+result, inline answer, page-list result and parse inside it, is derived again
+and overwritten. Deleting the directory loses
+only time. `cache: false` derives everything and reads and writes nothing.
+`prepareTables` prepares the query answers, `prepareTreeSqlTables` from
+`engine/sql-tables.mjs` by default; a host may wrap it to time or observe the
+preparation.
+
+`html` is the body before the site writer minifies it and before it unlinks
+links to pages its homepage cannot reach. Set it in
+`<div class="single-content"><div class="single-body">…</div></div>` with
+`styles`, the CSS the site theme applies to a page body, to show it as the page
+does. `styles` carries the theme's reset, body typography and ordinary link
+rules scoped to `.single-content`, so the body reads as the page does whatever
+the host's own styles, and sets the root font size on `:root`, since the
+theme measures its lengths in `rem`. Each finding is `{ file, line?, column?, severity, message }` and prints
+through `formatDiagnostic` as `file:line:column: severity: message`. `cache`
+says what the cache answered: `tree` is `"hit"` when the tree's records were
+reused whole, `"miss"` when they were derived, and `"off"` without the cache;
+`notes` counts the notes whose own records were derived again; `tables` is
+`"hit"` when the answers of the note and of every note it links were all
+reused, `"miss"` when any was prepared, and `"off"` without the cache.
+
+It throws when there is no configuration at or above `root`; when the file is
+not a note of the content tree (outside `paths.content`, in a skipped
+directory, or not Markdown); when a dependency's index has not been fetched or
+cannot be read, naming `package-build deps fetch`; when a note of the tree
+cannot be indexed, as the content-index build reports it; and when the
+configuration, fonts or dependency indexes keep changing while they are read,
+three times over. A finding in the
+rendered note itself is returned in `findings`, never thrown.
+
+`prepareTreeSqlTables(contentBase, { only })`, with one note's file or a
+collection of them, answers those notes' directives and generated sections and
+no other note's; its queries still read the whole corpus, so each note's
+results equal its results in a preparation of the whole tree.
+
 ## `./preview`
 
 Import the buffer-only renderer directly without loading the build pipeline:
@@ -2193,20 +2378,21 @@ const config = defineConfig({
 });
 ```
 
-| Export                     | Signature                          | Returns                                                    | Use it when                                                                                                                                                                                                                              |
-| -------------------------- | ---------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `defineConfig`             | `defineConfig(config)`             | `ContentBuildConfig` — the frozen, defaulted configuration | validating and normalizing a content configuration; every configuration reaches this function whether authored as YAML or as `.mjs`                                                                                                      |
-| `PACKAGE_KINDS`            | `const PACKAGE_KINDS`              | —                                                          | reading the three kinds of Foundry package a content module can be built into — `systems`, `modules`, and `documentation`, the kind that compiles no Foundry document at all (also the Foundry install directory name for the first two) |
-| `DOCUMENTATION_KIND`       | `const DOCUMENTATION_KIND`         | —                                                          | naming the `packageKind` value that compiles no Foundry documents, spelled once so the validator, the CLI and the compile passes cannot disagree about what it means                                                                     |
-| `AUTHOR_ROLES`             | `const AUTHOR_ROLES`               | `readonly string[]`                                        | reading the closed list an `authors` entry's `role` is drawn from — the configuration check refuses any other value                                                                                                                      |
-| `RELATIONSHIP_KEYS`        | `const RELATIONSHIP_KEYS`          | `readonly string[]`                                        | reading every key a declared relationship may carry — the configuration check refuses anything else, and the manifest writer drops the ones Foundry's own schema does not name                                                           |
-| `compilesFoundryDocuments` | `compilesFoundryDocuments(config)` | `boolean`                                                  | checking whether a resolved configuration compiles Foundry documents at all — false only for a `documentation` package                                                                                                                   |
-| `PACK_DOCUMENT_TYPES`      | `const PACK_DOCUMENT_TYPES`        | —                                                          | reading the Foundry document types this toolchain is able to compile a compendium pack of                                                                                                                                                |
-| `DEFAULT_PATHS`            | `const DEFAULT_PATHS`              | —                                                          | reading the conventional directory layout a build reads from and writes to, relative to `rootDir`                                                                                                                                        |
-| `DEFAULT_ADDRESS_SCHEME`   | `const DEFAULT_ADDRESS_SCHEME`     | —                                                          | reading an unconfigured repository's address-scheme defaults (`prefix`, where the content tree mounts inside the package)                                                                                                                |
-| `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`     | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                              |
-| `publishesContentPages`    | `publishesContentPages(config)`    | `boolean`                                                  | checking whether the authored content tree contains notes beyond its homepage, shared by site, PDF, index, and Foundry address emission                                                                                                  |
-| `siteBase`                 | `siteBase(config)`                 | `string`                                                   | reading the path a package's site is served at — `site.base` where the configuration states one, `/<contentPackage>/` otherwise                                                                                                          |
+| Export                     | Signature                                            | Returns                                                    | Use it when                                                                                                                                                                                                                                                                                                                                         |
+| -------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defineConfig`             | `defineConfig(config)`                               | `ContentBuildConfig` — the frozen, defaulted configuration | validating and normalizing a content configuration; every configuration reaches this function whether authored as YAML or as `.mjs`                                                                                                                                                                                                                 |
+| `PACKAGE_KINDS`            | `const PACKAGE_KINDS`                                | —                                                          | reading the three kinds of Foundry package a content module can be built into — `systems`, `modules`, and `documentation`, the kind that compiles no Foundry document at all (also the Foundry install directory name for the first two)                                                                                                            |
+| `DOCUMENTATION_KIND`       | `const DOCUMENTATION_KIND`                           | —                                                          | naming the `packageKind` value that compiles no Foundry documents, spelled once so the validator, the CLI and the compile passes cannot disagree about what it means                                                                                                                                                                                |
+| `AUTHOR_ROLES`             | `const AUTHOR_ROLES`                                 | `readonly string[]`                                        | reading the closed list an `authors` entry's `role` is drawn from — the configuration check refuses any other value                                                                                                                                                                                                                                 |
+| `RELATIONSHIP_KEYS`        | `const RELATIONSHIP_KEYS`                            | `readonly string[]`                                        | reading every key a declared relationship may carry — the configuration check refuses anything else, and the manifest writer drops the ones Foundry's own schema does not name                                                                                                                                                                      |
+| `compilesFoundryDocuments` | `compilesFoundryDocuments(config)`                   | `boolean`                                                  | checking whether a resolved configuration compiles Foundry documents at all — false only for a `documentation` package                                                                                                                                                                                                                              |
+| `PACK_DOCUMENT_TYPES`      | `const PACK_DOCUMENT_TYPES`                          | —                                                          | reading the Foundry document types this toolchain is able to compile a compendium pack of                                                                                                                                                                                                                                                           |
+| `DEFAULT_PATHS`            | `const DEFAULT_PATHS`                                | —                                                          | reading the conventional directory layout a build reads from and writes to, relative to `rootDir`                                                                                                                                                                                                                                                   |
+| `DEFAULT_ADDRESS_SCHEME`   | `const DEFAULT_ADDRESS_SCHEME`                       | —                                                          | reading an unconfigured repository's address-scheme defaults (`prefix`, where the content tree mounts inside the package)                                                                                                                                                                                                                           |
+| `DERIVED_SYSTEM_VERSION`   | `const DERIVED_SYSTEM_VERSION`                       | —                                                          | the loader-only symbol key `defineConfig` uses internally to receive a resolved system version; not something a configuration author writes                                                                                                                                                                                                         |
+| `publishesContentPages`    | `publishesContentPages(config)`                      | `boolean`                                                  | checking whether the authored content tree contains notes beyond its homepage, shared by site, PDF, index, and Foundry address emission                                                                                                                                                                                                             |
+| `siteBase`                 | `siteBase(config)`                                   | `string`                                                   | reading the path a package's site is served at — `site.base` where the configuration states one, `/<contentPackage>/` otherwise                                                                                                                                                                                                                     |
+| `siteBuildConfig`          | `siteBuildConfig(config, { root, baseUrl, assets })` | `ContentBuildConfig`                                       | selecting internal www by default, explicit root-derived CDN over configured assets, and low-level baseUrl/assets over derived values; exposes effective homepage/site.base/site.assets without changing authored configuration; the caller first validates the authored homepage with `checkHomepage`; the CLI uses it before index/body preflight |
 
 ## `./config`
 
@@ -2637,6 +2823,10 @@ preparation and kept separate.
 `prepareTreeSqlTables` retains the complete record membership when opening a
 public database, so derived citations can distinguish hidden notes from
 unknown addresses. Only public records contribute rendered sources and links.
+`prepareTreeSqlTables(contentBase, { only })`, with one note's file, answers
+that note's directives and generated sections and no other note's; its queries
+still read the whole corpus, so its results equal that note's in a preparation
+of the whole tree.
 
 | Export                 | Contract                                                                                                                     |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |