@heroiclands/package-build 25.6.2 → 25.7.0

package/engine/site-render.mjs

@@ -67,11 +67,10 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { LEXICAL_LINK_CLASS } from "./dictionary-layout.mjs";
-import { createRenderer } from "./content-render.mjs";
-import { resolvePathname } from "./pathnames.mjs";
+import { siteBodyRenderer } from "./site-page.mjs";
 import { minifyHtml } from "./html-minify.mjs";
 import { mapWorld } from "./map-places.mjs";
 import {
@@ -81,7 +80,7 @@ import {
     siteFontsDestination,
 } from "./script-font-delivery.mjs";
 import { buildSite, gatesFailed } from "./site-build.mjs";
-import { readCachedNavigation, siteSettings } from "./site-config.mjs";
+import { checkNavigation, readCachedNavigation, siteSettings } from "./site-config.mjs";
 import { atomFeed, robotsTxt, sitemapIndexXml, sitemapXml } from "./site-files.mjs";
 import {
     pageAddress,
@@ -548,8 +547,7 @@ export function writeSite({
  *   becomes its page.
  */
 export function packageSite({ config, built, settings, navigation = [], year }) {
-    const renderer = createRenderer("web", { icons: config.icons });
-    const resolveSrc = (src) => resolvePathname(src, config)?.web ?? null;
+    const renderBody = siteBodyRenderer(config);
     const { site: from } = built;
     const relative = (file) =>
         file ? path.relative(process.cwd(), file).split(path.sep).join("/") : undefined;
@@ -582,7 +580,7 @@ export function packageSite({ config, built, settings, navigation = [], year })
             params: data,
             date: isPost(data) ? data.data?.date : undefined,
             weight: data.weight,
-            content: renderer.render(markdown, { runs: from.runs, figures, resolveSrc }),
+            content: renderBody(markdown, { runs: from.runs, figures }),
             source: relative(page.file),
             search: search(data),
         };
@@ -595,7 +593,7 @@ export function packageSite({ config, built, settings, navigation = [], year })
             title: text(home.data.title),
             url: from.base,
             params: home.data,
-            content: renderer.render(home.body, { runs: from.runs, resolveSrc }),
+            content: renderBody(home.body, { runs: from.runs }),
             source: relative(home.file),
             search: search(home.data),
         });
@@ -657,6 +655,128 @@ export function deliverSiteFonts(config, out) {
     return { findings, count: copyScriptFonts(config, dest, ["woff2"]), dest };
 }
 
+/**
+ * @typedef {object} SiteInputs
+ * @property {import("./site-config.mjs").NavigationEntry[]} navigation The selected menu.
+ * @property {Record<string, string>} files Text artifacts relative to the site's output.
+ */
+
+/**
+ * @callback SiteInputsProvider
+ * @param {{config: import("../content-config.mjs").ContentBuildConfig}} options Frozen effective configuration.
+ * @returns {SiteInputs|Promise<SiteInputs>} Inputs prepared before content rendering.
+ */
+
+/**
+ * Refuse a symlink anywhere along a provider module or output path.
+ * @param {string} file The absolute path.
+ */
+function checkInputSymlinks(file) {
+    const absolute = path.resolve(file);
+    let current = path.parse(absolute).root;
+    for (const segment of absolute.slice(current.length).split(path.sep)) {
+        current = path.join(current, segment);
+        const stat = fs.lstatSync(current, { throwIfNoEntry: false });
+        if (!stat) break;
+        if (stat.isSymbolicLink()) {
+            throw new Error(`site.inputs refuses a symlink at ${current}`);
+        }
+        if (!stat.isDirectory()) break;
+    }
+}
+
+/**
+ * Read the one optional local input provider. It runs before content work.
+ * @param {object} config The effective configuration.
+ * @returns {Promise<SiteInputs>} Validated navigation and unvalidated text artifacts.
+ */
+async function readSiteInputs(config) {
+    if (!config.site.inputs) return { navigation: readCachedNavigation(config), files: {} };
+    const modulePath = path.resolve(config.rootDir, config.site.inputs);
+    checkInputSymlinks(modulePath);
+    const provider = (await import(pathToFileURL(modulePath).href)).default;
+    if (typeof provider !== "function")
+        throw new TypeError("site.inputs must export a default function");
+    const inputs = await provider({ config });
+    if (!inputs || typeof inputs !== "object" || Array.isArray(inputs)) {
+        throw new TypeError("site.inputs must return {navigation, files}");
+    }
+    return {
+        navigation: checkNavigation(inputs.navigation, "site.inputs.navigation"),
+        files: inputs.files,
+    };
+}
+
+/**
+ * Validate every provider artifact before the output tree can be replaced.
+ * @param {Record<string, string>} files Text artifacts.
+ * @param {object} options Output and builder-owned paths.
+ * @param {string} options.out Site output directory.
+ * @param {object} options.site Resolved site settings.
+ * @param {object[]} options.pages Rendered pages.
+ * @returns {[string, string][]} Absolute destination/content pairs.
+ */
+function siteInputFiles(files, { out, site, pages }) {
+    if (!files || typeof files !== "object" || Array.isArray(files)) {
+        throw new TypeError(
+            "site.inputs.files must be a mapping of relative paths to UTF-8 strings",
+        );
+    }
+    if (!Object.keys(files).length) return [];
+    const reservedTrees = new Set(
+        [
+            "assets",
+            "fonts",
+            "pagefind",
+            "tags",
+            ...fs.readdirSync(SITE_STATIC_DIR),
+            ...siteThemeAssets().map((asset) => asset.path.split("/")[0]),
+        ].map((name) => name.toLowerCase()),
+    );
+    const owned = [
+        "_headers",
+        "_redirects",
+        "sitemap.xml",
+        "sitemap-index.xml",
+        "robots.txt",
+        "404.html",
+    ];
+    for (const page of siteTree(site, pages))
+        owned.push(
+            path
+                .relative(out, pageFile(site, out, page.url))
+                .split(path.sep)
+                .join("/"),
+        );
+    if (site.feed) owned.push(`${site.feed.section}/atom.xml`);
+    const ownedPaths = owned.map((name) => name.toLowerCase());
+    /** @type {string[]} */
+    const seen = [];
+    const conflicts = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+    return Object.entries(files).map(([name, content]) => {
+        const lower = name.toLowerCase();
+        if (
+            !name.split("/").every((segment) => /^[a-z0-9][a-z0-9._-]*$/i.test(segment)) ||
+            typeof content !== "string"
+        )
+            throw new TypeError(
+                `site.inputs.files: ${name} must be a plain relative path with UTF-8 text`,
+            );
+        if (
+            lower.endsWith(".html") ||
+            reservedTrees.has(lower.split("/")[0]) ||
+            [...ownedPaths, ...seen].some((other) => conflicts(lower, other))
+        )
+            throw new TypeError(
+                `site.inputs.files: ${name} collides with a builder-owned or provider file`,
+            );
+        seen.push(lower);
+        const file = path.join(out, ...name.split("/"));
+        checkInputSymlinks(file);
+        return [file, content];
+    });
+}
+
 /**
  * Build a package's site from its content tree and write it.
  *
@@ -677,11 +797,17 @@ export function deliverSiteFonts(config, out) {
  *   What the build found, and, when it found nothing that stops it, what was
  *   written, the pages it was written from and how a note rendered again
  *   becomes its page. `written` is `null` when a gate fired.
- * @throws {Error} When the site's settings or its cached menu cannot be read.
+ * With `site.inputs`, the local default-exported provider receives `{config}`
+ * and supplies the navigation plus text artifacts. All artifact paths are checked
+ * before replacing output; artifacts are then written after the renderer clears
+ * and writes the site, and included in `written.files`.
+ *
+ * @throws {Error} When the site's settings, cached menu or input provider fail,
+ *   or a provider artifact is unsafe or collides with builder-owned output.
  */
 export async function buildPackageSite({ config, out, year, progress = () => {} }) {
     const settings = siteSettings({ config });
-    const navigation = readCachedNavigation(config);
+    const { navigation, files } = await readSiteInputs(config);
     progress("indexing content");
     const sqlTables = await prepareTreeSqlTables(config.paths.content, {
         skipDirectories: config.skipDirectories,
@@ -691,7 +817,13 @@ export async function buildPackageSite({ config, out, year, progress = () => {}
     const built = buildSite({ config, sqlTables, progress });
     if (gatesFailed(built.gates)) return { built, written: null, fonts: null };
     const { site, pages, pageOf } = packageSite({ config, built, settings, navigation, year });
+    const artifacts = siteInputFiles(files, { out, site, pages });
     const written = writeSite({ site, pages, out, progress });
+    for (const [file, content] of artifacts) {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, content, "utf8");
+        written.files.push(file);
+    }
     const fonts = deliverSiteFonts(config, out);
     return { built, written, fonts, site, pages, pageOf };
 }

package/engine/site-serve.mjs

@@ -94,7 +94,7 @@ export async function serveSite({
 }) {
     // Refuse a site that cannot be described before starting its server.
     siteSettings({ config });
-    readCachedNavigation(config);
+    if (!config.site.inputs) readCachedNavigation(config);
     root = path.resolve(root);
     out = path.resolve(out);
     let timer = null;

package/engine/sql-tables.mjs

@@ -72,6 +72,7 @@ import { sqlQueriesInMarkdown } from "./markdown-expressions.mjs";
 // The record accessors only — see `engine/index-records.mjs`.
 import { authoredFrontmatter, isNoteRecord, noteFile, sortKeysDeep } from "./index-records.mjs";
 import { nameSortOf } from "./name-sort.mjs";
+import { outsideOnly } from "./prepared-only.mjs";
 
 /** Rendered in a cell whose value is absent. */
 const EMPTY_CELL = "—";
@@ -1613,8 +1614,8 @@ export async function prepareInlineSqlExpressions(db, sources) {
  *   surface publishes to.
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
- * @param {string} [opts.only] - One note file to give sections to; absent,
- *   every note.
+ * @param {string|Set<string>} [opts.only] - The note file, or files, to give
+ *   sections to; absent, every note.
  * @param {Map<string, object>} [opts.foreignIndex] - The fetched indexes, whose
  *   places, affiliations and works the lists take in.
  * @param {object} [opts.config] - The resolved configuration.
@@ -1685,7 +1686,7 @@ export async function generatedSectionsFor(
             type: note.type,
             shortcode: note.shortcode,
         });
-        if (owners.has(key) && (only === undefined || fileOf(note) === only))
+        if (owners.has(key) && !outsideOnly(only, fileOf(note)))
             lexical.set(fileOf(note), owners.get(key));
     }
     return { sections, views: new Set(views.keys()), derived, lexical, declared };
@@ -1897,6 +1898,9 @@ export async function cachedDependencies(config) {
  *   generated sections take in, where the caller holds them already; absent,
  *   they are read from the cache.
  * @param {import("./content-session.mjs").ContentSyntax} [opts.syntax] - Exact-text scanner projections.
+ * @param {string|Iterable<string>} [opts.only] - One note's file, or several:
+ *   answer their directives and give them their generated sections, and no
+ *   other note's. The queries still read the whole corpus.
  * @returns {Promise<Map<string, object[]>|undefined>} Results by note path,
  *   carrying `inline` and `pageLists` beside them, or nothing when the tree
  *   holds no such directive and no note is given a generated section.
@@ -1912,6 +1916,7 @@ export async function prepareTreeSqlTables(
         audience = "all",
         foreignIndex,
         syntax,
+        only,
     } = {},
 ) {
     // Imported here rather than at module scope: the index reaches the pack
@@ -1919,6 +1924,7 @@ export async function prepareTreeSqlTables(
     // module they load would close a cycle and leave `BasePackCompiler`
     // uninitialised for whichever module the runtime happened to load first.
     const { indexRecordsFor } = await import("./content-index.mjs");
+    if (only !== undefined && typeof only !== "string") only = new Set(only);
     const notes = parsed ?? new Map();
     const allRecords =
         records ?? indexRecordsFor({ contentBase, config, skipDirectories, parsed: notes });
@@ -1937,6 +1943,7 @@ export async function prepareTreeSqlTables(
     for (const record of indexRecords) {
         if (!isNoteRecord(record)) continue;
         const absPath = noteFile(contentBase, record);
+        if (outsideOnly(only, absPath)) continue;
         const { body, frontmatter } = notes.get(absPath) ?? parseMarkdownFile(absPath);
         if (
             body &&
@@ -1971,6 +1978,7 @@ export async function prepareTreeSqlTables(
         foreignIndex: foreign,
         config,
         all: allRecords,
+        only,
     });
     if (
         !sources.length &&
@@ -2036,6 +2044,7 @@ export async function prepareTreeSqlTables(
             parsed,
             derived: derivedOnly.derived,
             all: allRecords,
+            only,
         });
         joinGeneratedSections(generated, sources, notes);
         const prepared = await prepareSqlTables(db, sources, {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "25.6.2",
+    "version": "25.7.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -40,6 +40,11 @@
             "import": "./engine/site-preview.mjs",
             "default": "./engine/site-preview.mjs"
         },
+        "./note-page": {
+            "types": "./types/engine/note-page.d.mts",
+            "import": "./engine/note-page.mjs",
+            "default": "./engine/note-page.mjs"
+        },
         "./content-config": {
             "types": "./types/content-config.d.mts",
             "import": "./content-config.mjs"

package/site-theme/static/css/style.css

@@ -3,6 +3,10 @@
    Dark fantasy / manuscript aesthetic
    ============================================ */
 
+/* Each stretch between a note-body comment and its closing comment styles
+   what the renderer writes into a page body. A host showing one note's body,
+   such as a preview, takes exactly these stretches as the note's styles. */
+/* note-body */
 :root {
   --bg:            #0f1923;
   --bg-deeper:     #0a1219;
@@ -67,6 +71,7 @@
   --content-width: 100%;
   --content-narrow: 100%;
 }
+/* /note-body */
 
 /* ---- Reset ---- */
 
@@ -103,6 +108,7 @@ a:hover {
   color: var(--accent-hover);
 }
 
+/* note-body */
 /* Inline body links get a subtle underline on hover so they feel
    tactile without competing with headings or navigation. Links
    inside utility contexts (cards, nav, TOC) opt out via more
@@ -114,6 +120,7 @@ a:hover {
 .single-body a:hover {
   border-bottom-color: var(--accent-dim);
 }
+/* /note-body */
 
 img {
   max-width: 100%;
@@ -1000,6 +1007,7 @@ a.tag:hover {
   line-height: 1.6;
 }
 
+/* note-body */
 /* ---- Article Content ---- */
 
 .single-content {
@@ -1735,6 +1743,8 @@ a.tag:hover {
   cursor: help;
 }
 
+/* /note-body */
+
 /* ---- The draft notice ----
 
    A page's statement that its own content is not settled, at the head of the
@@ -2727,6 +2737,7 @@ summary.info-sidebar-title::after {
   }
 }
 
+/* note-body */
 /* ---- Cartouches ----
 
    Named-entity SVGs rendered as ornamental accents on culture-flavored
@@ -2927,6 +2938,7 @@ summary.info-sidebar-title::after {
     height: 3.25rem;
   }
 }
+/* /note-body */
 
 /* ---- Related card (bottom of article) ----
 
@@ -2993,6 +3005,7 @@ summary.info-sidebar-title::after {
   border-bottom-color: var(--accent-dim);
 }
 
+/* note-body */
 /* A drawing the build sets inline — the map in a place's From here section —
    scales to its figure, and scrolls rather than shrinking past legibility on
    a phone. */
@@ -3110,3 +3123,4 @@ summary.info-sidebar-title::after {
 .script :is(em, strong) { font-style:normal; font-weight:inherit; font-synthesis:none; }
 .emph-rubric { color:var(--rubric); }
 .emph-overline { text-decoration-line:overline; text-decoration-skip-ink:none; }
+/* /note-body */

package/types/content-config.d.mts

@@ -25,6 +25,26 @@ export function siteBase(config: {
         base: string;
     };
 }): string;
+/**
+ * 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: ContentBuildConfig, { root, baseUrl, assets }?: {
+    root?: string | undefined;
+    baseUrl?: string | undefined;
+    assets?: string | undefined;
+}): ContentBuildConfig;
 /**
  * Whether this package publishes the pages its content tree compiles to.
  *
@@ -700,6 +720,13 @@ export type ContentBuildConfigInput = {
      * receive the notes that name none.
      */
     packs: PackSpec[];
+    /**
+     * Site settings;
+     * inputs names the optional local input provider.
+     */
+    site?: (Record<string, any> & {
+        inputs?: string;
+    }) | undefined;
     /**
      * Layout overrides. See {@link DEFAULT_PATHS}.
      */
@@ -802,6 +829,13 @@ export type ContentBuildConfig = {
      * the one reader of it.
      */
     assetRoot: string | null;
+    /**
+     * Frozen site settings;
+     * inputs is the local provider path or an empty string.
+     */
+    site: Readonly<Record<string, any> & {
+        inputs: string;
+    }>;
     paths: Readonly<ResolvedPaths>;
     /**
      * `null` for a `documentation`

package/types/engine/cdn-publish.d.mts

@@ -58,6 +58,24 @@ export function s3Store({ endpoint, bucket, accessKeyId, secretAccessKey, fetch:
  * @returns {CdnStore} The read-only store.
  */
 export function publicStore(host: string, fetchImpl?: typeof fetch): CdnStore;
+/**
+ * Internal storage: HTTPS reads and rsync writes of the planned bytes only.
+ *
+ * The default uses the operator's normal atlas account. An explicitly configured
+ * SSH alias may select the forced-rrsync account with a relative `cdn` destination.
+ * SSH configuration and its agent supply keys; no remote shell is requested.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.destination] - `host:/srv/preview/cdn` or `alias:cdn`.
+ * @param {typeof fetch} [opts.fetch] - The fetch to use for public reads.
+ * @param {(args: string[]) => Promise<unknown>} [opts.transfer] - Run rsync.
+ * @returns {CdnStore} The store.
+ */
+export function internalStore({ destination, fetch: fetchImpl, transfer, }?: {
+    destination?: string | undefined;
+    fetch?: typeof fetch | undefined;
+    transfer?: ((args: string[]) => Promise<unknown>) | undefined;
+}): CdnStore;
 /**
  * One picture to publish.
  *
@@ -220,6 +238,10 @@ export const CDN_ENV: Readonly<{
     accessKeyId: string;
     secretAccessKey: string;
 }>;
+/** The internal CDN's public origin. Reads never require SSH credentials. */
+export const INTERNAL_CDN_HOST: "https://cdn.internal.heroiclands.org";
+/** The manual operator's ordinary SSH account on atlas. */
+export const INTERNAL_CDN_DESTINATION: "atlas:/srv/preview/cdn";
 /**
  * One picture to publish.
  */

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

@@ -227,10 +227,17 @@ export function resolveCultures(records: Array<Record<string, any>>, { contentPa
  * @param {Iterable<string>} [options.nameTypes] - Additional bare name kinds from configured type declarations.
  * @param {ReturnType<typeof import("./content-timings.mjs").createContentTimings>} [options.timings] -
  *   Invocation stage accounting, which records each phase of the derivation.
+ * @param {NoteDerivationCache} [options.cache] - Earlier work to answer from:
+ *   each note's parse, and the records derived from one note alone, which
+ *   depend on that note and on the context the tree gives every note (the
+ *   setting date and calendars, the addresses the notes declare, the asset
+ *   records, the address context and the configured kinds). Not consulted
+ *   for the records when `syntax` is given. Every pass that reads the whole
+ *   tree runs whatever the cache holds.
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
-export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, rootDir, languages, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, timings, }: {
+export function collectContentIndex(contentBase: string, { contentPackage, currentDate, defaultCalendar, configFile, rootDir, languages, skipDirectories, assetsBase, manifest, problems, addressContext, foreignRecord, parsed, sources, syntax, nameTypes, timings, cache, }: {
     contentPackage: string;
     skipDirectories: readonly string[];
     assetsBase?: string | undefined;
@@ -270,6 +277,7 @@ export function collectContentIndex(contentBase: string, { contentPackage, curre
             hits: any;
         };
     } | undefined;
+    cache?: NoteDerivationCache | undefined;
 }): Array<Record<string, any>>;
 /**
  * Serialize records as JSON Lines.
@@ -316,9 +324,11 @@ export function serializeContentIndex(records: Array<Record<string, any>>): stri
  * @param {Map<string, object>} [opts.foreignIndex] - Captured dependency address view.
  * @param {ReturnType<typeof import("./content-timings.mjs").createContentTimings>} [opts.timings] -
  *   Invocation stage accounting.
+ * @param {NoteDerivationCache} [opts.cache] - Earlier parses and per-note
+ *   records to answer from; see {@link collectContentIndex}.
  * @returns {object[]} One record per note, plus one per documentation entry.
  */
-export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, sources, syntax, nameTypes, foreignIndex, timings, }?: {
+export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectories, problems, parsed, sources, syntax, nameTypes, foreignIndex, timings, cache, }?: {
     contentBase?: string | undefined;
     assetsBase?: string | undefined;
     config?: object | undefined;
@@ -348,6 +358,7 @@ export function indexRecordsFor({ contentBase, assetsBase, config, skipDirectori
             hits: any;
         };
     } | undefined;
+    cache?: NoteDerivationCache | undefined;
 }): object[];
 /**
  * Prepare the complete bodies a content-index publication describes.
@@ -409,6 +420,29 @@ export function emitContentIndex({ contentBase, outDir, config, publication }?:
         rows: number;
     };
 };
+/**
+ * Earlier derivation work {@link collectContentIndex} may answer from, such as
+ * {@link module :engine/note-cache.noteTree}'s store.
+ */
+export type NoteDerivationCache = {
+    /**
+     * - Reads
+     * one note, as {@link module :engine/helpers.parseMarkdownFile} does.
+     */
+    parse?: typeof import("./helpers.mjs").parseMarkdownFile | undefined;
+    /**
+     * - A key for the
+     * context the tree gives each note's records, or nothing when it has none.
+     */
+    context: (value: unknown) => string | undefined;
+    /**
+     * -
+     * The records one note derives: the stored ones when that note's text and
+     * the context are unchanged, else `derive()`'s. Either is the caller's to
+     * change.
+     */
+    records: (absPath: string, context: string | undefined, derive: () => object[]) => object[];
+};
 /**
  * A captured source context, consumed without mutation by the synchronous emitter.
  */

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

@@ -29,5 +29,25 @@ export function highlightRules(scope: string): string;
  * @returns {string} The stylesheet.
  */
 export function siteCodeStylesheet(scope?: string): string;
+/**
+ * The CSS the site theme applies to a page body: its custom properties, the
+ * body's text, named blocks, figures, verse, footnotes, unresolved and draft
+ * links, cartouches, glyphs, alerts, spoilers, dictionary lists and faces,
+ * then the highlighted-code rules a site links as `css/code.css`.
+ *
+ * Read from the theme's own stylesheet, the stretches it marks `note-body`,
+ * so a rule changed there changes here. The rules are scoped as the theme
+ * scopes them: the body sits in a `.single-body` inside a `.single-content`.
+ * The theme's page-wide rules for the reset, the body's typography and the
+ * ordinary link come first, scoped to `.single-content`, so a body set in that
+ * wrapper reads as the page does whatever the host's own styles; the one
+ * exception is the root font size, set on `:root`, since every length the
+ * theme writes in `rem` is measured against it.
+ *
+ * @returns {string} The stylesheet.
+ * @throws {Error} When the theme's stylesheet marks no body rules, or lacks
+ *   one of the page-wide rules.
+ */
+export function noteBodyStylesheet(): string;
 /** The roots the shipped content stylesheet scopes its rules to. */
 export const CONTENT_ROOTS: ":is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)";

package/types/engine/derived-sections.d.mts

@@ -53,8 +53,8 @@ export function drawMapsFrom(records: object[], { outDir, foreignIndex, config,
  * @param {object} [opts.config] - The resolved configuration.
  * @param {(file:string)=>string|undefined} [opts.rawOf] - Captured source locators.
  * @param {object[]} [opts.all=records] - Complete records for settlement validation.
- * @param {string} [opts.only] - One note file to give sections to; absent,
- *   every note.
+ * @param {string|Set<string>} [opts.only] - The note file, or files, to give
+ *   sections to; absent, every note.
  * @returns {Map<string, Map<string, string>>} Note file to its sections, each
  *   keyed by its slug, for every note given at least one.
  */
@@ -64,7 +64,7 @@ export function derivedSections(records: object[], { fileOf, foreignIndex, confi
     config?: object | undefined;
     rawOf?: ((file: string) => string | undefined) | undefined;
     all?: object[] | undefined;
-    only?: string | undefined;
+    only?: string | Set<string> | undefined;
 }): Map<string, Map<string, string>>;
 /**
  * The heading each kind of place is grouped under, in the order the place

package/types/engine/event-views.d.mts

@@ -14,12 +14,13 @@ export function selfForms(record: object): string[];
  * @param {Iterable<object>} records - The content-index records.
  * @param {(record: object) => string} fileOf - A record's note file, as the
  *   prepared results are keyed.
- * @param {string} [only] - One note file to give views to, every note's being
- *   read for them; absent, every note is given its views.
+ * @param {string|Set<string>} [only] - The note file, or files, to give views
+ *   to, every note's being read for them; absent, every note is given its
+ *   views.
  * @returns {Promise<Map<string, Map<string, string>>>} Note file to its views,
  *   each keyed by its slug, for every note given at least one.
  */
-export function eventViewSections(db: object, records: Iterable<object>, fileOf: (record: object) => string, only?: string): Promise<Map<string, Map<string, string>>>;
+export function eventViewSections(db: object, records: Iterable<object>, fileOf: (record: object) => string, only?: string | Set<string>): Promise<Map<string, Map<string, string>>>;
 /**
  * The views, in the order
  * {@link module:engine/generated-sections.GENERATED_SECTIONS} sets them in.