@heroiclands/package-build 24.1.0 → 24.1.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @heroiclands/package-build
 
+## 24.1.1
+
+### Patch Changes
+
+**Content builds**
+
+- Build indexes, calendars, assets and packs with
+  `package-build content build --calendaria-version 1.4.2`, sharing preparation
+  across validation and compilation.
+
 ## 24.1.0
 
 ### Minor Changes

package/README.md

@@ -16,6 +16,8 @@ npm install -D @heroiclands/package-build
 
 The generated project includes a homepage, website and book targets, npm scripts, and a local `.gitignore`. [Getting started](docs/getting-started.md) routes you to a [system](docs/guides/system-project.md), [module](docs/guides/module-project.md), or [content authoring](docs/authoring/first-note.md) path. The [content-language-server](https://github.com/HeroicLands/content-language-server) provides editor navigation and completion.
 
+Build indexes, calendars, staged assets and packs together with `package-build content build --calendaria-version 1.4.2`. The [complete content build](docs/commands.md#package-build-content-build) shares one source capture across publication, lint, links and compilation and reports each build stage's time.
+
 Run selected content operations together with `package-build content run index lint links compile`. The [shared content command](docs/commands.md#package-build-content-run-targets) captures one source tree for the selected checks and outputs; standalone commands remain available.
 
 Language annotations keep authored spelling: `[Zaron]{lang=vyl}` stays Roman.

package/bin/content-commands.mjs

@@ -135,6 +135,10 @@ import { serveSite } from "../engine/site-serve.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
 import { prepareLinkSqlTables, prepareTreeSqlTables } from "../engine/sql-tables.mjs";
+import { createContentTimings } from "../engine/content-timings.mjs";
+import { emitCalendarArtifacts } from "../engine/calendar-artifacts.mjs";
+import { stagePackageBuildAssets } from "../engine/build-assets.mjs";
+import { DEPLOYED_ASSET_TYPES } from "../engine/asset-types.mjs";
 import { createContentSession, CONTENT_TARGETS } from "../engine/content-session.mjs";
 import { createFirstUseChecker } from "../engine/first-use.mjs";
 import { createNameCatalog, createNamesReport, namesReportFinding } from "../engine/names.mjs";
@@ -297,7 +301,7 @@ export function registerContentCommands(cli) {
         .command(proseCommand())
         .command(contentFormatCommand())
         .command(withIndexPreflight(linksCommand()))
-        .command(withIndexPreflight(contentCommand()))
+        .command(contentCommand())
         .command(formatCommand())
         .command(markdownCommand())
         .command(
@@ -1494,25 +1498,187 @@ function markdownCommand() {
     };
 }
 
-/**
- * `package-build links` — check that every link in a content tree lands.
- *
- * Reports a dead `#anchor`, a dead qualified address, and a wikilink authored
- * in frontmatter, plus a vendored manifest that has drifted out of reach. All
- * of it is package-agnostic, so a consumer needs no script of its own: the
- * manifest directory is the only thing it might name, and that comes from its
- * configuration.
- *
- * @returns {object} The yargs command module.
- */
-// eslint-disable-next-line
+/** Content operations with a shared invocation-local capture. */
 function contentCommand() {
     return {
-        command: "content <action> <targets..>",
+        command: "content",
+        describe: "Run content operations in one in-memory session",
+        builder: (yargs) =>
+            yargs
+                .command(withIndexPreflight(contentRunCommand()))
+                .command(contentBuildCommand())
+                .demandCommand(1, "Choose content run or content build."),
+        handler: () => {},
+    };
+}
+
+/** The complete build writes only outside the captured input roots. */
+function contentBuildOutputs(config, packaging) {
+    const roots = [
+        config.paths.content,
+        ...DEPLOYED_ASSET_TYPES.map((entry) => path.resolve(config.paths.assets, entry.root)),
+    ];
+    const stage = path.resolve(packaging.rootDir, packaging.stageDir);
+    const outputs = [
+        config.paths.contentIndex,
+        config.paths.packJson,
+        config.paths.stage,
+        stage,
+        path.join(config.rootDir, "build/calendars"),
+    ];
+    const contains = (parent, child) => {
+        const relative = path.relative(path.resolve(parent), path.resolve(child));
+        return (
+            relative === "" ||
+            (!relative.startsWith(`..${path.sep}`) &&
+                relative !== ".." &&
+                !path.isAbsolute(relative))
+        );
+    };
+    for (const output of [...outputs, ...packaging.assets.map(({ to }) => path.resolve(stage, to))])
+        for (const root of roots)
+            if (contains(root, output) || contains(output, root))
+                throw new Error(
+                    `content build output ${output} overlaps captured input ${root}; keep build outputs outside source roots`,
+                );
+    return [
+        ...new Set([
+            config.paths.contentIndex,
+            config.paths.packJson,
+            path.join(config.rootDir, "build/calendars"),
+            ...config.packDirectories.map((name) => path.join(config.paths.stage, name)),
+        ]),
+    ];
+}
+
+/** Publish, generate calendars, stage assets and check/compile one live session. */
+function contentBuildCommand() {
+    return {
+        command: "build",
+        describe:
+            "Publish fresh indexes, emit calendars, stage assets, lint, check links and compile",
+        builder: (yargs) =>
+            yargs
+                .option("calendaria-version", {
+                    type: "string",
+                    demandOption: true,
+                    describe: "Calendaria import format version",
+                })
+                .check((argv) => {
+                    if (!/^\d+\.\d+\.\d+$/.test(argv.calendariaVersion))
+                        throw new Error("--calendaria-version requires a version such as 1.4.2");
+                    return true;
+                }),
+        handler: async (argv) => {
+            const timings = createContentTimings();
+            let session;
+            const shared = {
+                ...argv,
+                references: true,
+                [PREPARATION_REPORTED]: true,
+                [REPORTED_FAILURES]: new Set(),
+            };
+            const fail = (error) => {
+                reportContentFailure(error, shared);
+                process.exitCode = 1;
+            };
+            try {
+                const config = loadPackConfig();
+                const marker = path.join(config.paths.contentIndex, ".publication-ready");
+                fs.rmSync(marker, { force: true });
+                const packaging = loadPackageBuildConfig();
+                const outputs = contentBuildOutputs(config, packaging);
+                for (const output of outputs) fs.rmSync(output, { recursive: true, force: true });
+                cachedMetadataIndexes(config);
+                session = await createContentSession({ config, timings, trackChanges: true });
+                shared[CONTENT_SESSION] = session;
+                let prepared = false;
+                const reportedProblems = new Set();
+                try {
+                    assertCompendiumOperation(config, "compile");
+                    await session.prepare(["index"]);
+                    prepared = true;
+                } catch (error) {
+                    if (error.findings) {
+                        for (const finding of error.findings) {
+                            emitDiagnostic(finding);
+                            reportedProblems.add(finding);
+                        }
+                        shared[REPORTED_FAILURES].add(error);
+                        process.exitCode = 1;
+                    } else fail(error);
+                }
+                for (const problem of session.problems) {
+                    if (!reportedProblems.has(problem)) emitDiagnostic(problem);
+                    process.exitCode = 1;
+                }
+                let staged = false;
+                if (
+                    prepared &&
+                    (await timings.measure("index publication", () =>
+                        contentIndexCommand().handler(shared),
+                    ))
+                ) {
+                    fs.writeFileSync(marker, `${config.contentPackage}\n`);
+                    try {
+                        await timings.measure("calendars", () => {
+                            const result = emitCalendarArtifacts({
+                                config,
+                                calendariaVersion: argv.calendariaVersion,
+                                sources: session.sources,
+                            });
+                            log.info(
+                                `${result.calendars} calendars emitted (${result.files} files).`,
+                            );
+                        });
+                        await timings.measure("assets", () =>
+                            stagePackageBuildAssets({
+                                config: packaging,
+                                packConfig: config,
+                                session,
+                            }),
+                        );
+                        staged = true;
+                    } catch (error) {
+                        fail(error);
+                    }
+                    try {
+                        session.assertUnchanged();
+                    } catch (error) {
+                        fs.rmSync(marker, { force: true });
+                        throw error;
+                    }
+                }
+                await timings.measure("validation", () => lintCommand().handler(shared));
+                await timings.measure("links", () => linksCommand().handler(shared));
+                if (staged)
+                    await timings.measure("compile", () =>
+                        packageCommand().handler({ ...shared, action: "compile" }),
+                    );
+            } catch (error) {
+                fail(error);
+            } finally {
+                const summary = timings.snapshot();
+                log.info(
+                    `Content timings (exclusive): ${Object.entries(summary.stages)
+                        .map(([name, ms]) => `${name} ${Number(ms).toFixed(1)} ms`)
+                        .join("; ")}; total ${summary.totalMs.toFixed(1)} ms.`,
+                );
+                log.info(
+                    `Content work: ${session?.sources.size ?? 0} sources; ${session?.parsed.size ?? 0} parsed notes; ${session?.records.length ?? 0} records; reuse ${JSON.stringify(summary.hits)}; peak RSS ${(process.resourceUsage().maxRSS / 1024).toFixed(1)} MiB.`,
+                );
+                session?.dispose();
+            }
+        },
+    };
+}
+
+function contentRunCommand() {
+    return {
+        command: "run <targets..>",
         describe: "Run selected content operations with one in-memory source capture",
         builder: (yargs) =>
             yargs
-                .positional("action", { type: "string", choices: ["run"] })
                 .positional("targets", { type: "string", array: true, choices: CONTENT_TARGETS })
                 .option("references", {
                     type: "boolean",
@@ -1801,9 +1967,11 @@ function contentIndexCommand() {
                         `${config.contentPackage} → ${path.relative(process.cwd(), written.file)} ` +
                             `(${written.rows} ${relation} rows)`,
                     );
+                return true;
             } catch (err) {
                 reportContentFailure(err, argv);
                 process.exitCode = 1;
+                return false;
             } finally {
                 if (!argv[CONTENT_SESSION]) session?.dispose();
             }

package/bin/package-build.mjs

@@ -87,20 +87,13 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
-import { checkForeignAssetBindings } from "../engine/asset-bindings.mjs";
-import { emitDiagnostic, formatDiagnostic, positionOfYamlPath } from "../engine/diagnostics.mjs";
+import { loadAssetTransform, stagePackageBuildAssets } from "../engine/build-assets.mjs";
+import { emitDiagnostic, formatDiagnostic } from "../engine/diagnostics.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments, siteBase } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
-import { cleanBuildArtifacts, resetStage, stageAssets } from "../stage.mjs";
-import { rowsStagingPictureRoots, stagePackageAssets } from "../engine/asset-shipping.mjs";
-import { baseStyleStageEntry } from "../engine/base-styles.mjs";
-import {
-    checkScriptFonts,
-    copyScriptFonts,
-    STAGED_FONTS_DIR,
-} from "../engine/script-font-delivery.mjs";
+import { cleanBuildArtifacts, resetStage } from "../stage.mjs";
 import {
     CDN_ENV,
     cdnCredentials,
@@ -438,171 +431,13 @@ function cleanCommand() {
     };
 }
 
-/**
- * A finding for each `packageBuild.assets` row that would stage a picture root
- * itself, located at the row's `from` when the configuration is YAML.
- *
- * @param {readonly {from: string, to: string}[]} rows - The configured rows.
- * @param {{rootDir: string, assetsBase: string}} opts - Where they resolve.
- * @returns {object[]} The findings.
- */
-function pictureRootRowFindings(rows, { rootDir, assetsBase }) {
-    const offending = rowsStagingPictureRoots(rows, { rootDir, assetsBase });
-    if (!offending.length) return [];
-    const file = packConfigPath();
-    const text =
-        file.endsWith(".yaml") || file.endsWith(".yml") ? fs.readFileSync(file, "utf8") : "";
-    return offending.map(({ index, from, root }) => ({
-        file,
-        ...(text ? positionOfYamlPath(text, ["packageBuild", "assets", index, "from"]) : {}),
-        severity: "error",
-        message:
-            `\`packageBuild.assets[${index}]\` copies \`${from}\`, which reaches ${root}/ — ` +
-            "the stage copies the icon and image roots itself, flat and filtered by " +
-            "each file's provenance, so a row copying them would ship every file " +
-            "unfiltered. Remove the row",
-    }));
-}
-
-/**
- * The repository's `packageBuild.assetTransform`, loaded.
- *
- * One loader for every command that writes a picture, so the stage and the CDN
- * hold the same bytes for the same file.
- *
- * @param {object} config - The resolved package-build configuration.
- * @returns {Promise<((sourcePath: string) => string|null|undefined)|undefined>}
- *   The transform, or `undefined` when the repository names none.
- */
-async function loadAssetTransform(config) {
-    if (!config.assetTransform) return undefined;
-    const module = await import(`file://${config.assetTransform}`).catch((err) =>
-        die(
-            `cannot load \`packageBuild.assetTransform\` ` +
-                `(${config.assetTransform}): ${err.message}`,
-        ),
-    );
-    const transform = module.transform;
-    if (typeof transform !== "function") {
-        die(
-            `\`packageBuild.assetTransform\` ` +
-                `(${config.assetTransform}) exports no \`transform\` ` +
-                `function. It must export ` +
-                `\`transform(sourcePath) -> string | null\`.`,
-        );
-    }
-    return transform;
-}
-
-/**
- * `assets` — stage the repository's static files into the package root.
- *
- * The table is data (`packageBuild.assets`). A repository that has to *change*
- * a file on the way — SoHL rewrites each SVG's hard-coded fill so icons follow
- * the Foundry theme — names a module in `packageBuild.assetTransform`, whose
- * `transform(sourcePath)` returns replacement text or `null` to copy verbatim.
- * That is the one genuine piece of code in the job, and it stays the
- * repository's.
- *
- * @returns {object} The yargs command module.
- */
+/** Stage the configured package assets. */
 function assetsCommand() {
     return {
         command: "assets",
         describe: "Stage static assets into the package root",
         builder: (y) => y,
-        handler: handler(async () => {
-            const config = loadPackageBuildConfig();
-            const packConfig = loadPackConfig();
-            const assetsBase = packConfig.paths.assets;
-            const findings = [
-                ...pictureRootRowFindings(config.assets, {
-                    rootDir: config.rootDir,
-                    assetsBase,
-                }),
-                ...checkForeignAssetBindings(packConfig, { assets: config.assets }),
-            ];
-            if (findings.length) {
-                const error = new Error(findings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-
-            const transform = await loadAssetTransform(config);
-
-            // `to:` is relative to the staged package root, so a
-            // repository's table reads `lang`, not `build/stage/lang`.
-            const entries = config.assets.map(({ from, to }) => [
-                from,
-                path.join(config.stageDir, to),
-            ]);
-            let { entries: count, files } = stageAssets(entries, {
-                cwd: config.rootDir,
-                transform,
-            });
-
-            // The picture roots, staged by the toolchain rather than by a row:
-            // flat, filtered by each file's provenance, and listed in the
-            // package's asset set.
-            const pictures = stagePackageAssets({
-                assetsBase,
-                contentPackage: packConfig.contentPackage,
-                stageDir: path.resolve(config.rootDir, config.stageDir),
-                // The manifest's title names the set; a package with none is
-                // named by its content package.
-                title:
-                    typeof config.manifest?.title === "string" && config.manifest.title.trim() ?
-                        config.manifest.title
-                    :   packConfig.contentPackage,
-                transform,
-                shippingLicenses: config.shippingLicenses,
-            });
-            if (pictures.findings.length) {
-                const error = new Error(pictures.findings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-            files += pictures.staged.length;
-            if (pictures.staged.length || pictures.excluded.length) {
-                console.log(
-                    `Pictures: ${pictures.staged.length} staged, ` +
-                        `${pictures.excluded.length} left out by provenance.`,
-                );
-            }
-
-            // Staged in its own pass, without the repository's transform: the
-            // sheet is this toolchain's file rather than one of the
-            // repository's assets, and a `transform` written to retheme a
-            // package's own SVGs has no business being handed it.
-            if (config.baseStyles) {
-                const staged = stageAssets([baseStyleStageEntry(config.stageDir)], {
-                    cwd: config.rootDir,
-                });
-                count += staged.entries;
-                files += staged.files;
-            }
-
-            // The installed fonts, when the package has installed the fonts
-            // package and a note sets text in one of its faces: the
-            // stylesheet, the WOFF2 files and the licence, which the
-            // manifest's `styles` names.
-            const fontFindings = checkScriptFonts(packConfig);
-            if (fontFindings.length) {
-                const error = new Error(fontFindings.map(formatDiagnostic).join("\n"));
-                error.located = true;
-                die(error);
-            }
-            const fonts = copyScriptFonts(
-                packConfig,
-                path.resolve(config.rootDir, config.stageDir, STAGED_FONTS_DIR),
-                ["woff2"],
-            );
-            if (fonts) {
-                count += 1;
-                files += fonts;
-            }
-            console.log(`✅ Static assets staged (${count} entries, ${files} files).`);
-        }),
+        handler: handler(() => stagePackageBuildAssets()),
     };
 }
 

package/docs/commands.md

@@ -1556,6 +1556,89 @@ package-build: This repository declares no end-to-end suite to `run`. Name one u
 
 ## Content operations
 
+### `package-build content build`
+
+**NAME**
+
+Build indexes, calendars, assets and packs from one captured content tree.
+
+**SYNOPSIS**
+
+```text
+package-build content build --calendaria-version <version>
+```
+
+**DESCRIPTION**
+
+The complete content build runs these existing operations in order:
+
+1. Capture authored sources and prepare and publish fresh metadata, dictionary
+   and terms indexes.
+2. Emit calendar definitions and Calendaria imports from the published index.
+3. Stage the configured assets, including calendars, provenance-filtered
+   pictures, base styles and fonts.
+4. Run content lint, link checks and pack compilation with the same live session.
+
+Finish dependency fetching and source generation before invoking the command.
+Public and complete SQL preparations remain separate and each is reused by
+operations needing that audience. No resolved index or source cache survives
+into another invocation. Standalone commands and `content run` remain available.
+
+The command clears its index directory, generated calendar directory, pack JSON
+and configured compiled pack directories before preparing the new build. Other
+stage files, including a manifest written by a parallel packaging task, remain.
+Use `package-build stage reset` before starting the complete packaging workflow
+when the entire stage must start empty. Build output paths must be outside the
+captured content and picture roots. A phase that changes those inputs fails the
+build, invalidates publication readiness and stops further use of the capture;
+source generation belongs before this command.
+
+After all three index files are published successfully, the command writes
+`<paths.contentIndex>/.publication-ready` (normally
+`build/content-index/.publication-ready`). It removes that marker at startup.
+The marker means this invocation published a complete fresh index, even when
+calendar emission, asset staging, lint, link checks or compilation later fails.
+A subsequent index consumer can check it to report independent findings after a
+build failure. Clear the marker before a surrounding workflow starts as well,
+so failures before the command starts cannot expose an earlier run's index.
+Never restore the marker or resolved indexes from a cache.
+
+Preparation failure blocks publication and compilation but preserves useful
+independent lint and link findings. Calendar or asset failure blocks compilation;
+ordinary lint or link findings do not block an otherwise valid compile. Pack
+generation still refuses to compile incomplete output. An advisory warning does
+not fail the command.
+
+The final timing summary includes eager capture and index derivation, SQL by
+audience, publication, calendars, assets, validation, rendering and native pack
+compilation. Stage times are exclusive: a nested SQL preparation is charged to
+SQL rather than its calling stage. Counts, preparation reuse and peak process
+RSS accompany the timings; importing the CLI and validating its arguments happen
+before the measured build interval.
+
+**OPTIONS**
+
+| Option                 | Type   | Default  | Description                            |
+| ---------------------- | ------ | -------- | -------------------------------------- |
+| `--calendaria-version` | string | required | Calendaria import version, e.g. 1.4.2. |
+
+**EXIT STATUS**
+
+0 when every operation succeeds. 1 when arguments, preparation or any build
+operation fails. Publication readiness alone does not mean the build passed.
+
+**EXAMPLES**
+
+```bash
+package-build deps fetch
+package-build content build --calendaria-version 1.4.2
+```
+
+**SEE ALSO**
+
+`package-build content run`, `package-build content-index`, `package-build calendars`,
+`package-build assets`, `package-build package compile`.
+
 ### `package-build content run <targets..>`
 
 **NAME**

package/engine/build-assets.mjs

@@ -0,0 +1,179 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadPackageBuildConfig } from "../config.mjs";
+import { loadPackConfig, packConfigPath } from "./pack-config.mjs";
+import { checkForeignAssetBindings } from "./asset-bindings.mjs";
+import { formatDiagnostic, positionOfYamlPath } from "./diagnostics.mjs";
+import { stageAssets } from "../stage.mjs";
+import { rowsStagingPictureRoots, stagePackageAssets } from "./asset-shipping.mjs";
+import { baseStyleStageEntry } from "./base-styles.mjs";
+import { checkScriptFonts, copyScriptFonts, STAGED_FONTS_DIR } from "./script-font-delivery.mjs";
+
+/**
+ * A finding for each `packageBuild.assets` row that would stage a picture root
+ * itself, located at the row's `from` when the configuration is YAML.
+ *
+ * @param {readonly {from: string, to: string}[]} rows - The configured rows.
+ * @param {{rootDir: string, assetsBase: string}} opts - Where they resolve.
+ * @returns {object[]} The findings.
+ */
+function pictureRootRowFindings(rows, { rootDir, assetsBase }) {
+    const offending = rowsStagingPictureRoots(rows, { rootDir, assetsBase });
+    if (!offending.length) return [];
+    const file = packConfigPath();
+    const text =
+        file.endsWith(".yaml") || file.endsWith(".yml") ? fs.readFileSync(file, "utf8") : "";
+    return offending.map(({ index, from, root }) => ({
+        file,
+        ...(text ? positionOfYamlPath(text, ["packageBuild", "assets", index, "from"]) : {}),
+        severity: "error",
+        message:
+            `\`packageBuild.assets[${index}]\` copies \`${from}\`, which reaches ${root}/ — ` +
+            "the stage copies the icon and image roots itself, flat and filtered by " +
+            "each file's provenance, so a row copying them would ship every file " +
+            "unfiltered. Remove the row",
+    }));
+}
+
+/**
+ * The repository's `packageBuild.assetTransform`, loaded.
+ *
+ * One loader for every command that writes a picture, so the stage and the CDN
+ * hold the same bytes for the same file.
+ *
+ * @param {object} config - The resolved package-build configuration.
+ * @returns {Promise<((sourcePath: string) => string|null|undefined)|undefined>}
+ *   The transform, or `undefined` when the repository names none.
+ */
+export async function loadAssetTransform(config) {
+    if (!config.assetTransform) return undefined;
+    const module = await import(pathToFileURL(config.assetTransform).href).catch((err) => {
+        throw new Error(
+            `cannot load \`packageBuild.assetTransform\` (${config.assetTransform}): ${err.message}`,
+        );
+    });
+    const transform = module.transform;
+    if (typeof transform !== "function") {
+        throw new Error(
+            `\`packageBuild.assetTransform\` ` +
+                `(${config.assetTransform}) exports no \`transform\` ` +
+                `function. It must export ` +
+                `\`transform(sourcePath) -> string | null\`.`,
+        );
+    }
+    return transform;
+}
+
+/**
+ * Stage static files, provenance-filtered pictures, base styles and fonts.
+ * @param {object} [options]
+ * @param {ReturnType<typeof loadPackageBuildConfig>} [options.config]
+ * @param {import("../content-config.mjs").ContentBuildConfig} [options.packConfig]
+ * @param {import("./content-session.mjs").ContentSession} [options.session]
+ */
+export async function stagePackageBuildAssets({
+    config = loadPackageBuildConfig(),
+    packConfig = loadPackConfig(),
+    session,
+} = {}) {
+    const assetsBase = packConfig.paths.assets;
+    const findings = [
+        ...pictureRootRowFindings(config.assets, {
+            rootDir: config.rootDir,
+            assetsBase,
+        }),
+        ...checkForeignAssetBindings(packConfig, { assets: config.assets }),
+    ];
+    if (findings.length) {
+        const error = new Error(findings.map(formatDiagnostic).join("\n"));
+        error.located = true;
+        throw error;
+    }
+
+    const transform = await loadAssetTransform(config);
+
+    // `to:` is relative to the staged package root, so a
+    // repository's table reads `lang`, not `build/stage/lang`.
+    const entries = config.assets.map(({ from, to }) => [from, path.join(config.stageDir, to)]);
+    let { entries: count, files } = stageAssets(entries, {
+        cwd: config.rootDir,
+        transform,
+    });
+
+    // The picture roots, staged by the toolchain rather than by a row:
+    // flat, filtered by each file's provenance, and listed in the
+    // package's asset set.
+    const pictures = stagePackageAssets({
+        assetsBase,
+        contentPackage: packConfig.contentPackage,
+        stageDir: path.resolve(config.rootDir, config.stageDir),
+        // The manifest's title names the set; a package with none is
+        // named by its content package.
+        title:
+            typeof config.manifest?.title === "string" && config.manifest.title.trim() ?
+                config.manifest.title
+            :   packConfig.contentPackage,
+        transform,
+        shippingLicenses: config.shippingLicenses,
+    });
+    if (pictures.findings.length) {
+        const error = new Error(pictures.findings.map(formatDiagnostic).join("\n"));
+        error.located = true;
+        throw error;
+    }
+    files += pictures.staged.length;
+    if (pictures.staged.length || pictures.excluded.length) {
+        console.log(
+            `Pictures: ${pictures.staged.length} staged, ` +
+                `${pictures.excluded.length} left out by provenance.`,
+        );
+    }
+
+    // Staged in its own pass, without the repository's transform: the
+    // sheet is this toolchain's file rather than one of the
+    // repository's assets, and a `transform` written to retheme a
+    // package's own SVGs has no business being handed it.
+    if (config.baseStyles) {
+        const staged = stageAssets([baseStyleStageEntry(config.stageDir)], {
+            cwd: config.rootDir,
+        });
+        count += staged.entries;
+        files += staged.files;
+    }
+
+    // The installed fonts, when the package has installed the fonts
+    // package and a note sets text in one of its faces: the
+    // stylesheet, the WOFF2 files and the licence, which the
+    // manifest's `styles` names.
+    const fontFindings = checkScriptFonts(packConfig, session);
+    if (fontFindings.length) {
+        const error = new Error(fontFindings.map(formatDiagnostic).join("\n"));
+        error.located = true;
+        throw error;
+    }
+    const fonts = copyScriptFonts(
+        packConfig,
+        path.resolve(config.rootDir, config.stageDir, STAGED_FONTS_DIR),
+        ["woff2"],
+        session,
+    );
+    if (fonts) {
+        count += 1;
+        files += fonts;
+    }
+    console.log(`✅ Static assets staged (${count} entries, ${files} files).`);
+}

package/engine/calendar-artifacts.mjs

@@ -77,16 +77,20 @@ function readIndex(file) {
  *
  * @param {object} opts
  * @param {object} opts.config - Resolved content configuration.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Captured authored text for diagnostics.
  * @param {string} opts.calendariaVersion - Version whose import format is targeted.
  * @returns {{directory: string, calendars: number, files: number}}
  */
-export function emitCalendarArtifacts({ config, calendariaVersion } = {}) {
+export function emitCalendarArtifacts({ config, calendariaVersion, sources } = {}) {
     if (!config) throw new Error("calendar emission requires a content configuration");
     if (!/^\d+\.\d+\.\d+$/.test(calendariaVersion ?? "")) {
         throw new Error("calendar emission requires a Calendaria version such as 1.4.2");
     }
 
     const root = config.rootDir;
+    const rawSource = (file) =>
+        sources?.get(path.resolve(root, file))?.raw ??
+        fs.readFileSync(path.resolve(root, file), "utf8");
     const contentBase = path.resolve(root, config.paths.content);
     const indexFile = path.resolve(
         root,
@@ -108,7 +112,7 @@ export function emitCalendarArtifacts({ config, calendariaVersion } = {}) {
     );
     const names = new Map();
     for (const note of calendars) {
-        const raw = fs.readFileSync(path.resolve(root, note.file), "utf8");
+        const raw = rawSource(note.file);
         const shortcode = note.fm.shortcode;
         if (typeof shortcode !== "string" || !/^[a-z0-9]+$/.test(shortcode)) {
             failAt(
@@ -135,7 +139,7 @@ export function emitCalendarArtifacts({ config, calendariaVersion } = {}) {
         failAt(
             note.file,
             "calendar notes require a world note declaring data.year",
-            fs.readFileSync(path.resolve(root, note.file), "utf8"),
+            rawSource(note.file),
             ["subType"],
         );
     }

package/engine/compendiums.mjs

@@ -96,6 +96,7 @@ export async function compilePacks({
         contentBase: config.paths.content,
         skipDirectories: config.skipDirectories,
     });
+    const measured = (name, work) => (session ? session.timings.measure(name, work) : work());
     const packNames = sourcePacks.filter((name) => !packName || name === packName);
 
     // A prebuilt pack's JSON is checked in rather than generated, so it is
@@ -114,12 +115,14 @@ export async function compilePacks({
     // content tree, and a package that ships only prebuilt packs has none at
     // all — so running it would fail the build over a tree nothing reads.
     if (needsGeneration) {
-        const errors = await generatePacksJson({
-            only: packName,
-            config,
-            session,
-            reportPreparation,
-        });
+        const errors = await measured("rendering/documents", () =>
+            generatePacksJson({
+                only: packName,
+                config,
+                session,
+                reportPreparation,
+            }),
+        );
         if (errors > 0) {
             throw new Error(
                 `Pack JSON generation reported ${errors} error(s); refusing to ` +
@@ -141,11 +144,13 @@ export async function compilePacks({
 
         const stage = path.join(stageDest, name);
         log.info(`Pack ${name}: compiling to LevelDB at ${stage}`);
-        await compilePack(source, stage, {
-            recursive: true,
-            log: false,
-            transformEntry: cleanPackEntry,
-        });
+        await measured("pack compilation", () =>
+            compilePack(source, stage, {
+                recursive: true,
+                log: false,
+                transformEntry: cleanPackEntry,
+            }),
+        );
 
         // A Scene's map image lives on an embedded Level, stored under its own
         // LevelDB key. Nothing in Foundry ties the two together on read: a

package/engine/content-session.mjs

@@ -13,6 +13,9 @@
 
 /** One invocation's authored sources and context-specific prepared views. */
 import path from "node:path";
+import fs from "node:fs";
+import { DEPLOYED_ASSET_TYPES } from "./asset-types.mjs";
+import { createContentTimings } from "./content-timings.mjs";
 import * as contentIndex from "./content-index.mjs";
 import * as blocks from "./content-blocks.mjs";
 import * as alerts from "./content-alerts.mjs";
@@ -52,6 +55,8 @@ import { lintNoteStates } from "./stub-lint.mjs";
  * @property {() => Promise<import("./content-index.mjs").PreparedContentIndex>} publication
  * @property {() => ReturnType<import("./compile-corpus.mjs").buildCompileCorpus>} compileCorpus
  * @property {(targets: readonly ContentTarget[]) => Promise<ContentSession>} prepare
+ * @property {ReturnType<typeof createContentTimings>} timings
+ * @property {() => void} assertUnchanged
  * @property {() => void} dispose
  */
 
@@ -71,6 +76,8 @@ export const CONTENT_TARGETS = Object.freeze(["index", "lint", "links", "compile
  * @param {string} [options.assetsBase] - Assets root, defaulting to configuration.
  * @param {readonly string[]} [options.skipDirectories] - Resolved content scope.
  * @param {ReturnType<typeof routerFor>} [options.router] - One router shared by this session's compile.
+ * @param {boolean} [options.trackChanges] - Snapshot physical input metadata for build phase guards.
+ * @param {ReturnType<typeof createContentTimings>} [options.timings] - Invocation stage accounting.
  * @returns {Promise<ContentSession>} Captured sources and lazy prepared views; dispose after use.
  */
 export async function createContentSession({
@@ -79,14 +86,36 @@ export async function createContentSession({
     assetsBase = config.paths.assets,
     skipDirectories = config.skipDirectories,
     router = routerFor(config),
+    timings = createContentTimings(),
+    trackChanges = false,
 } = {}) {
     const tree = path.resolve(contentBase);
     const assets = path.resolve(assetsBase);
     const scope = [...skipDirectories];
-    const inventory = captureContentSources(tree, assets, scope);
+    const inventory = timings.sync("source capture", () =>
+        captureContentSources(tree, assets, scope),
+    );
+    const fingerprint = (file) => {
+        const stat = fs.statSync(file, { throwIfNoEntry: false });
+        return stat ? `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}` : "absent";
+    };
+    const fingerprints =
+        trackChanges ?
+            new Map(
+                [
+                    ...new Set([
+                        tree,
+                        ...DEPLOYED_ASSET_TYPES.map((entry) => path.resolve(assets, entry.root)),
+                        ...inventory.paths.map((entry) => entry.file),
+                    ]),
+                ].map((file) => [file, fingerprint(file)]),
+            )
+        :   undefined;
     const parsed = new Map();
     const problems = [];
-    const foreign = loadForeignIndexes(config, [config.contentPackage]);
+    const foreign = timings.sync("dependency indexes", () =>
+        loadForeignIndexes(config, [config.contentPackage]),
+    );
     const syntaxCache = new Map();
     const prepared = new Map();
     let disposed = false;
@@ -104,23 +133,31 @@ export async function createContentSession({
             });
         return syntaxCache.get(text);
     };
-    const records = contentIndex.indexRecordsFor({
-        config,
-        contentBase: tree,
-        assetsBase: assets,
-        skipDirectories: scope,
-        sources: inventory.indexSources,
-        parsed,
-        problems,
-        foreignIndex: foreign.index,
-        syntax,
-    });
+    const records = timings.sync("index derivation", () =>
+        contentIndex.indexRecordsFor({
+            config,
+            contentBase: tree,
+            assetsBase: assets,
+            skipDirectories: scope,
+            sources: inventory.indexSources,
+            parsed,
+            problems,
+            foreignIndex: foreign.index,
+            syntax,
+        }),
+    );
     const memo = (key, make) => {
         active();
-        if (!prepared.has(key)) prepared.set(key, Promise.resolve().then(make));
+        if (!prepared.has(key))
+            prepared.set(
+                key,
+                Promise.resolve().then(() => timings.measure(key, make)),
+            );
+        else timings.hit(key);
         return prepared.get(key);
     };
     const session = {
+        timings,
         config,
         contentBase: tree,
         assetsBase: assets,
@@ -133,6 +170,17 @@ export async function createContentSession({
         problems,
         foreign,
         syntax,
+        /** Refuse a stale capture after any build phase changes an input. */
+        assertUnchanged() {
+            active();
+            if (!fingerprints)
+                throw new Error("Content change tracking was not enabled for this session");
+            for (const [file, before] of fingerprints)
+                if (fingerprint(file) !== before)
+                    throw new Error(
+                        `Content sources changed during the build: ${file}. Finish source generation before content build.`,
+                    );
+        },
         /** Refuse use with a different configuration, root, scope or router. */
         assertContext(options = {}) {
             active();

package/engine/content-timings.mjs

@@ -0,0 +1,67 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/** Sequential, nested stage accounting for one content invocation. */
+export function createContentTimings() {
+    const started = performance.now();
+    let changed = started;
+    const stack = ["orchestration"];
+    const stages = new Map();
+    const hits = new Map();
+    const account = () => {
+        const now = performance.now();
+        const name = stack.at(-1);
+        stages.set(name, (stages.get(name) ?? 0) + now - changed);
+        changed = now;
+    };
+    const begin = (name) => {
+        account();
+        stack.push(name);
+        return () => {
+            account();
+            stack.pop();
+        };
+    };
+    return {
+        /** @template T @param {string} name @param {() => T} work @returns {T} */
+        sync(name, work) {
+            const stop = begin(name);
+            try {
+                return work();
+            } finally {
+                stop();
+            }
+        },
+        /** @template T @param {string} name @param {() => Promise<T>|T} work @returns {Promise<T>} */
+        async measure(name, work) {
+            const stop = begin(name);
+            try {
+                return await work();
+            } finally {
+                stop();
+            }
+        },
+        /** @param {string} name */
+        hit(name) {
+            hits.set(name, (hits.get(name) ?? 0) + 1);
+        },
+        snapshot() {
+            account();
+            return {
+                totalMs: changed - started,
+                stages: Object.fromEntries(stages),
+                hits: Object.fromEntries(hits),
+            };
+        },
+    };
+}

package/engine/script-font-delivery.mjs

@@ -76,14 +76,15 @@ const FRONTMATTER = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
  *
  * @param {string} source - The note's file.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @param {import("./content-session.mjs").ContentNoteSource} [parsed] - Already parsed authored note.
  * @returns {string|undefined} The face's slug.
  */
-function writtenInFace(source, installed) {
+function writtenInFace(source, installed, parsed) {
     const yaml = FRONTMATTER.exec(source)?.[1];
     if (yaml === undefined) return undefined;
     let fm;
     try {
-        fm = YAML.parse(yaml);
+        fm = parsed ? parsed.frontmatter : YAML.parse(yaml);
     } catch {
         return undefined;
     }
@@ -102,10 +103,12 @@ function writtenInFace(source, installed) {
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {ReadonlySet<string>} The slugs of the faces used.
  */
-export function facesUsed(config, installed) {
-    const known = usedFaces.get(config);
+export function facesUsed(config, installed, session) {
+    const cacheKey = session ?? config;
+    const known = usedFaces.get(cacheKey);
     if (known) return known;
     const used = new Set();
     const content =
@@ -119,9 +122,9 @@ export function facesUsed(config, installed) {
             const full = path.join(dir, entry.name);
             if (entry.isDirectory()) walk(full);
             else if (entry.isFile() && entry.name.endsWith(".md")) {
-                const source = fs.readFileSync(full, "utf8");
+                const source = session?.sources.get(full)?.raw ?? fs.readFileSync(full, "utf8");
                 if (/^\s*writtenIn:/m.test(source)) {
-                    const face = writtenInFace(source, installed);
+                    const face = writtenInFace(source, installed, session?.parsed.get(full));
                     if (face) used.add(face);
                 }
                 if (!/\bfont=/.test(source)) continue;
@@ -135,7 +138,7 @@ export function facesUsed(config, installed) {
         }
     };
     if (content && fs.existsSync(content)) walk(content);
-    usedFaces.set(config, used);
+    usedFaces.set(cacheKey, used);
     return used;
 }
 
@@ -143,15 +146,16 @@ export function facesUsed(config, installed) {
  * The installed package, when this consumer is to ship it.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources.
  * @returns {import("./script-fonts.mjs").ScriptFonts|undefined} The package, or
  *   `undefined` without a root, an install, a manifest, or a note that sets
  *   text in one of its faces.
  */
-function delivered(config) {
+function delivered(config, session) {
     if (!config?.rootDir) return undefined;
     const installed = resolveScriptFonts(config.rootDir);
     if (!installed?.manifest) return undefined;
-    return facesUsed(config, installed).size ? installed : undefined;
+    return facesUsed(config, installed, session).size ? installed : undefined;
 }
 
 /**
@@ -159,12 +163,13 @@ function delivered(config) {
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {string[]} formats - The font formats the target uses: `woff2`, `ttf`.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{root: string, version: string, files: string[]}|undefined} The
  *   files, sorted: `fonts.css`, `LICENSE` and every file in `fonts/` of a
  *   listed format. `undefined` when the consumer ships none.
  */
-export function scriptFontFiles(config, formats) {
-    const installed = delivered(config);
+export function scriptFontFiles(config, formats, session) {
+    const installed = delivered(config, session);
     if (!installed) return undefined;
     const fontsDir = path.join(installed.root, "fonts");
     const fonts =
@@ -250,10 +255,11 @@ export function stagedStylesheet(css, staged) {
  * @param {string} dest - The directory to fill; created when there is
  *   something to put in it.
  * @param {string[]} formats - The font formats the target uses.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {number} How many files were written; 0 when the consumer ships none.
  */
-export function copyScriptFonts(config, dest, formats) {
-    const found = scriptFontFiles(config, formats);
+export function copyScriptFonts(config, dest, formats, session) {
+    const found = scriptFontFiles(config, formats, session);
     if (!found) return 0;
     const staged = new Set(found.files);
     for (const file of found.files) {
@@ -274,11 +280,12 @@ export function copyScriptFonts(config, dest, formats) {
  * stylesheet, the licence and every file the manifest lists.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{file: string, severity: "error", message: string}[]} One finding
  *   per missing file, located at the manifest; empty when the consumer ships none.
  */
-export function checkScriptFonts(config) {
-    const installed = delivered(config);
+export function checkScriptFonts(config, session) {
+    const installed = delivered(config, session);
     if (!installed) return [];
     const manifest = path.join(installed.root, FONTS_MANIFEST);
     const wanted = new Set([STYLESHEET, LICENSE]);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "24.1.0",
+    "version": "24.1.1",
     "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",

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

@@ -0,0 +1,23 @@
+/**
+ * The repository's `packageBuild.assetTransform`, loaded.
+ *
+ * One loader for every command that writes a picture, so the stage and the CDN
+ * hold the same bytes for the same file.
+ *
+ * @param {object} config - The resolved package-build configuration.
+ * @returns {Promise<((sourcePath: string) => string|null|undefined)|undefined>}
+ *   The transform, or `undefined` when the repository names none.
+ */
+export function loadAssetTransform(config: object): Promise<((sourcePath: string) => string | null | undefined) | undefined>;
+/**
+ * Stage static files, provenance-filtered pictures, base styles and fonts.
+ * @param {object} [options]
+ * @param {ReturnType<typeof loadPackageBuildConfig>} [options.config]
+ * @param {import("../content-config.mjs").ContentBuildConfig} [options.packConfig]
+ * @param {import("./content-session.mjs").ContentSession} [options.session]
+ */
+export function stagePackageBuildAssets({ config, packConfig, session, }?: {
+    config?: Readonly<import("../config.mjs").PackageBuildConfig> | undefined;
+    packConfig?: import("../content-config.mjs").ContentBuildConfig | undefined;
+    session?: import("./content-session.mjs").ContentSession | undefined;
+}): Promise<void>;

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

@@ -3,11 +3,15 @@
  *
  * @param {object} opts
  * @param {object} opts.config - Resolved content configuration.
+ * @param {Map<string, {raw: string}>} [opts.sources] - Captured authored text for diagnostics.
  * @param {string} opts.calendariaVersion - Version whose import format is targeted.
  * @returns {{directory: string, calendars: number, files: number}}
  */
-export function emitCalendarArtifacts({ config, calendariaVersion }?: {
+export function emitCalendarArtifacts({ config, calendariaVersion, sources }?: {
     config: object;
+    sources?: Map<string, {
+        raw: string;
+    }> | undefined;
     calendariaVersion: string;
 }): {
     directory: string;

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

@@ -8,9 +8,11 @@
  * @param {string} [options.assetsBase] - Assets root, defaulting to configuration.
  * @param {readonly string[]} [options.skipDirectories] - Resolved content scope.
  * @param {ReturnType<typeof routerFor>} [options.router] - One router shared by this session's compile.
+ * @param {boolean} [options.trackChanges] - Snapshot physical input metadata for build phase guards.
+ * @param {ReturnType<typeof createContentTimings>} [options.timings] - Invocation stage accounting.
  * @returns {Promise<ContentSession>} Captured sources and lazy prepared views; dispose after use.
  */
-export function createContentSession({ config, contentBase, assetsBase, skipDirectories, router, }?: {
+export function createContentSession({ config, contentBase, assetsBase, skipDirectories, router, timings, trackChanges, }?: {
     config?: import("../content-config.mjs").ContentBuildConfig | undefined;
     contentBase?: string | undefined;
     assetsBase?: string | undefined;
@@ -21,6 +23,17 @@ export function createContentSession({ config, contentBase, assetsBase, skipDire
         packsOfType: (docType: string) => string[];
         defaultOf: (docType: string) => string | undefined;
     } | undefined;
+    trackChanges?: boolean | undefined;
+    timings?: {
+        sync<T>(name: string, work: () => T): T;
+        measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+        hit(name: string): void;
+        snapshot(): {
+            totalMs: number;
+            stages: any;
+            hits: any;
+        };
+    } | undefined;
 }): Promise<ContentSession>;
 /**
  * @typedef {"index"|"lint"|"links"|"compile"} ContentTarget
@@ -47,6 +60,8 @@ export function createContentSession({ config, contentBase, assetsBase, skipDire
  * @property {() => Promise<import("./content-index.mjs").PreparedContentIndex>} publication
  * @property {() => ReturnType<import("./compile-corpus.mjs").buildCompileCorpus>} compileCorpus
  * @property {(targets: readonly ContentTarget[]) => Promise<ContentSession>} prepare
+ * @property {ReturnType<typeof createContentTimings>} timings
+ * @property {() => void} assertUnchanged
  * @property {() => void} dispose
  */
 /**
@@ -96,6 +111,8 @@ export type ContentSession = {
     publication: () => Promise<import("./content-index.mjs").PreparedContentIndex>;
     compileCorpus: () => ReturnType<typeof import("./compile-corpus.mjs").buildCompileCorpus>;
     prepare: (targets: readonly ContentTarget[]) => Promise<ContentSession>;
+    timings: ReturnType<typeof createContentTimings>;
+    assertUnchanged: () => void;
     dispose: () => void;
 };
 import * as blocks from "./content-blocks.mjs";
@@ -106,3 +123,4 @@ import { captureContentSources } from "./content-sources.mjs";
 import { loadForeignIndexes } from "./metadata-index.mjs";
 import * as sql from "./sql-tables.mjs";
 import { buildLinkIndex } from "./content-links.mjs";
+import { createContentTimings } from "./content-timings.mjs";

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

@@ -0,0 +1,14 @@
+/** Sequential, nested stage accounting for one content invocation. */
+export function createContentTimings(): {
+    /** @template T @param {string} name @param {() => T} work @returns {T} */
+    sync<T>(name: string, work: () => T): T;
+    /** @template T @param {string} name @param {() => Promise<T>|T} work @returns {Promise<T>} */
+    measure<T>(name: string, work: () => Promise<T> | T): Promise<T>;
+    /** @param {string} name */
+    hit(name: string): void;
+    snapshot(): {
+        totalMs: number;
+        stages: any;
+        hits: any;
+    };
+};

package/types/engine/script-font-delivery.d.mts

@@ -7,19 +7,21 @@
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {import("./script-fonts.mjs").ScriptFonts} installed - The fonts package.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {ReadonlySet<string>} The slugs of the faces used.
  */
-export function facesUsed(config: DeliveryConfig, installed: import("./script-fonts.mjs").ScriptFonts): ReadonlySet<string>;
+export function facesUsed(config: DeliveryConfig, installed: import("./script-fonts.mjs").ScriptFonts, session?: import("./content-session.mjs").ContentSession): ReadonlySet<string>;
 /**
  * The files a target receives, as paths relative to the fonts package root.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
  * @param {string[]} formats - The font formats the target uses: `woff2`, `ttf`.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{root: string, version: string, files: string[]}|undefined} The
  *   files, sorted: `fonts.css`, `LICENSE` and every file in `fonts/` of a
  *   listed format. `undefined` when the consumer ships none.
  */
-export function scriptFontFiles(config: DeliveryConfig, formats: string[]): {
+export function scriptFontFiles(config: DeliveryConfig, formats: string[], session?: import("./content-session.mjs").ContentSession): {
     root: string;
     version: string;
     files: string[];
@@ -46,18 +48,20 @@ export function stagedStylesheet(css: string, staged: ReadonlySet<string>): stri
  * @param {string} dest - The directory to fill; created when there is
  *   something to put in it.
  * @param {string[]} formats - The font formats the target uses.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {number} How many files were written; 0 when the consumer ships none.
  */
-export function copyScriptFonts(config: DeliveryConfig, dest: string, formats: string[]): number;
+export function copyScriptFonts(config: DeliveryConfig, dest: string, formats: string[], session?: import("./content-session.mjs").ContentSession): number;
 /**
  * Whether the package ships what its manifest and stylesheet promise: the
  * stylesheet, the licence and every file the manifest lists.
  *
  * @param {DeliveryConfig} config - The resolved configuration.
+ * @param {import("./content-session.mjs").ContentSession} [session] - Captured sources when staging within a content build.
  * @returns {{file: string, severity: "error", message: string}[]} One finding
  *   per missing file, located at the manifest; empty when the consumer ships none.
  */
-export function checkScriptFonts(config: DeliveryConfig): {
+export function checkScriptFonts(config: DeliveryConfig, session?: import("./content-session.mjs").ContentSession): {
     file: string;
     severity: "error";
     message: string;