@heroiclands/package-build 22.22.0 → 22.24.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @heroiclands/package-build
 
+## 22.24.0
+
+### Minor Changes
+
+**Hero banners** — A page whose note names its own hero image shows that image, in place of the stock banner for its kind; a note naming none gets a band with no image.
+
+**Figures** — A numbered figure, table, listing or map reads as one block, its number and caption set beneath it rather than running on as body text, and a passage set apart as an aside draws as a box.
+
+**Pictures** — A portrait or an emblem draws at half the content column and a banner, plate or map at its full width, never wider than the size the picture was made at; a stated width still overrides the role's measure.
+
+**Installing** — The shared Hugo theme arrives with this package, so a site declares this package alone and needs no separate theme dependency.
+
+**Hero images** — The authoring guide states the three states of a note's hero image: a picture, a deliberate blank that declines one, and an absent key that takes the default for the note's type.
+
+## 22.23.0
+
+### Minor Changes
+
+**Figures**
+
+- A picture and the words about it are written as one block: the caption is optional, several pictures can share one, and a border is available.
+- Prose refers to a figure by name, in its own note or in another, and reads back its number, its number and caption, or the caption alone.
+- A figure drawn from a map counts as a Map, numbered the same way on every surface.
+- A figure holding one picture opens as an illustrated page in Foundry, with that viewer's own pop-out and zoom.
+
+**Pictures**
+
+- A picture carrying no caption draws no line beneath it, on a page, in a journal or in print.
+- A picture states what it is for, and is drawn at the size that choice gives it — never larger than it was made.
+- A page's hero image is 1792×768, and one of any other size is refused, naming the size to cut it to.
+
+**Art provenance**
+
+- A record saying a file is not machine-generated is published saying so.
+- A package may refuse generated art in its own tree.
+- A package may declare that a dependency's art answers its own addresses, and the book draws the replacement.
+
+**Notes**
+
+- A lore note states the occasions it records, each with a date and an optional recurrence, and publishes the next one due.
+- A note may write a shared field at the position it is being retired from, and the build accepts it with a warning rather than refusing the note.
+
+### Patch Changes
+
+**Item-frontmatter reference**: regenerating the page no longer renders a broken sentence for `affiliation`'s `title`, which now says plainly that a top-level key is refused outright.
+
 ## 22.22.0
 
 ### Minor Changes

package/README.md

@@ -33,6 +33,7 @@ The documentation lives in the Markdown files in this repository. Start with [th
 | Detailed format rules and examples                | [Format details](docs/reference/format-details.md)           |
 | Compendium routing and document builds            | [Packs](docs/guides/packs.md)                                |
 | Website build and publication                     | [Site](docs/guides/site.md)                                  |
+| What the theme draws on a page                    | [Theme pages](docs/reference/theme-pages.md)                 |
 | PDF book build                                    | [Book](docs/guides/book.md)                                  |
 | Icon generation and use                           | [Icons](docs/guides/icons.md)                                |
 | Reference pages and content indexes               | [Reference pages](docs/guides/reference-pages.md)            |

package/bin/content-commands.mjs

@@ -64,6 +64,7 @@ import {
 import { fetchNavigation, generateHugoConfig, writeHugoConfig } from "../engine/site-config.mjs";
 import { renderItemFieldReference, renderItemFieldsPage } from "../engine/field-reference.mjs";
 import { checkDocLinks, checkDocIndex } from "../engine/docs-checks.mjs";
+import { checkArtSlotSizes } from "../engine/art-fields.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintNoteStates } from "../engine/stub-lint.mjs";
 import { lintContentCharset } from "../engine/content-charset.mjs";
@@ -109,6 +110,7 @@ import {
     authoredFrontmatter,
     emitContentIndex,
     indexRecordsFor,
+    isAssetRecord,
     isNoteRecord,
     noteFile,
 } from "../engine/content-index.mjs";
@@ -139,6 +141,7 @@ import { buildMaps, FROM_ALL, MAP_DIR } from "../engine/map-build.mjs";
 import { CHART_HORIZON_DAYS } from "../engine/map-layout.mjs";
 import { GRAPHVIZ_ENGINES } from "../engine/map-graphviz.mjs";
 import { loadMapWorld } from "../engine/map-places.mjs";
+import { encodeAddresses } from "../engine/address-values.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -1175,6 +1178,32 @@ function lintCommand() {
                 });
                 for (const line of states.summary) log.info(line);
 
+                // Generated art, when this package declares it carries none.
+                // `records` already holds every asset of this build, so the
+                // check is a filter over the corpus already in hand rather
+                // than a second enumeration of the asset trees.
+                const generatedArt =
+                    config.forbidGeneratedArt ?
+                        records
+                            .filter(isAssetRecord)
+                            .filter((record) => record.asset.ai === true)
+                            .map((record) => ({
+                                file: path.join(config.paths.assets, record.asset.path),
+                                severity: "error",
+                                message:
+                                    `\`${encodeAddresses(record.address.canonical)}\` is ` +
+                                    "machine-generated art (`ai: true`), and " +
+                                    "`forbidGeneratedArt` refuses it in this package",
+                            }))
+                    :   [];
+
+                // A hero image against the size its slot is cut to, read
+                // from the records already in hand.
+                const artSizes = checkArtSlotSizes(records, {
+                    config,
+                    assetsBase: config.paths.assets,
+                });
+
                 const findings = [
                     ...addresses.findings,
                     ...frontmatter.findings,
@@ -1185,6 +1214,8 @@ function lintCommand() {
                     ...images.findings,
                     ...taskLists.findings,
                     ...states.findings,
+                    ...generatedArt,
+                    ...artSizes,
                 ];
                 // Only an **error** fails the run. Every finding was an error
                 // by then, so this changes nothing on its own —
@@ -1820,6 +1851,9 @@ function siteCommand() {
                 for (const e of result.footnoteErrors) {
                     emitDiagnostic({ ...e, severity: "error" });
                 }
+                for (const e of result.embedErrors) {
+                    emitDiagnostic({ ...e, severity: "error" });
+                }
                 // Reported the way the pack build reports the very same
                 // finding: `file:line:column: error: message`, path first, and
                 // the message from the shared table, not a
@@ -1862,7 +1896,8 @@ function siteCommand() {
                     result.headingErrors.length ||
                     result.footnoteErrors.length ||
                     result.wikiErrors.length ||
-                    result.imageErrors.length
+                    result.imageErrors.length ||
+                    result.embedErrors.length
                 ) {
                     process.exitCode = 1;
                     return;
@@ -2195,16 +2230,18 @@ async function fetchFromLocalArtifact(config, argv) {
 
 /**
  * `deps fetch` — fill the caches this build resolves other packages through:
- * the **content index** of every declared dependency, the **item catalogue**
- * of those additionally declaring `itemCatalog: true`, and the **site
- * navigation** heroiclands.org publishes, which the site build writes its
- * menu from.
- *
- * The two dependency sets differ deliberately. Citing another package's
- * *addresses* and embedding its *items* are separate edges, and a package may
- * have either without the other — `harn-ensemble` cites no foreign address and
- * embeds 324,016 item references. The navigation is fetched for every package,
- * because every package publishes a site.
+ * the **content index** of every declared dependency, the **item catalogue
+ * or asset archive** of those additionally declaring `itemCatalog: true` or
+ * `assetArchive: true`, and the **site navigation** heroiclands.org
+ * publishes, which the site build writes its menu from.
+ *
+ * The dependency sets differ deliberately. Citing another package's
+ * *addresses*, embedding its *items*, and staging its *asset bytes* are
+ * separate edges, and a package may declare any of them without the others —
+ * `harn-ensemble` cites no foreign address and embeds 324,016 item
+ * references. The navigation is fetched for every package, because every
+ * package publishes a site. A relationship declaring both `itemCatalog: true`
+ * and `assetArchive: true` is fetched once.
  *
  * Its own command rather than a step of `package compile` or `site`, so that
  * neither reaches the network. A build that downloads silently is not
@@ -2265,7 +2302,7 @@ function depsCommand() {
                 const indexes = await fetchAllMetadata(config);
                 if (indexes) log.info(`Fetched ${indexes} dependency content index(es).`);
                 const count = await fetchAllCatalogs(config);
-                if (count) log.info(`Fetched ${count} dependency catalogue(s).`);
+                if (count) log.info(`Fetched ${count} dependency catalogue(s) or archive(s).`);
                 if (!indexes && !count) {
                     // Distinguished from a package declaring nothing at all: a
                     // relationship may still be declared, just narrowed to the
@@ -2277,8 +2314,8 @@ function depsCommand() {
                     );
                     log.info(
                         declared ?
-                            "No declared dependency needs a fetched content index or item " +
-                                "catalogue."
+                            "No declared dependency needs a fetched content index, item " +
+                                "catalogue, or asset archive."
                         :   "This package declares no dependencies.",
                     );
                 }

package/ci/content-format-reference.mjs

@@ -137,7 +137,7 @@ const GENERATED_TABLES = [
             "| ------ | ---------- | ----------------- |",
             ...Object.entries(EXPRESSION_HELPERS).map(
                 ([name, { params, summary }]) =>
-                    `| \`${name}\` | \`${params}\` | ${cell(summary)} |`,
+                    `| \`${cell(name)}\` | \`${cell(params)}\` | ${cell(summary)} |`,
             ),
         ],
     },

package/content-config.mjs

@@ -368,7 +368,8 @@ export function publishesContentPages(config) {
  * @property {string} [stage]            Compiled LevelDB packs.
  * @property {string} [unpack]           Where `unpack` extracts JSON back to.
  * @property {string} [foreignCache]     Where a dependency declaring
- *                                       `itemCatalog: true` is unpacked.
+ *                                       `itemCatalog: true` or
+ *                                       `assetArchive: true` is unpacked.
  *                                       Inbound, and fetched rather than
  *                                       committed.
  * @property {string} [metadataCache]    Where a dependency's published content
@@ -486,6 +487,15 @@ export function publishesContentPages(config) {
  *                                   package this one targets — for a system
  *                                   relationship, `verified` is what
  *                                   `_stats.systemVersion` is stamped from.
+ * @property {boolean} [itemCatalog]  Whether `deps fetch` unpacks this
+ *                                   dependency's release archive and extracts
+ *                                   its Item packs, so the actors pass can
+ *                                   resolve embedded items this repository
+ *                                   does not hold. Needs a `manifest`.
+ * @property {boolean} [assetArchive]  Whether `deps fetch` unpacks this
+ *                                   dependency's release archive for its
+ *                                   asset bytes alone, building no item
+ *                                   catalogue from it. Needs a `manifest`.
  * @property {boolean} [contentIndex]  Whether `deps fetch` fetches this
  *                                   dependency's content index. Default
  *                                   `true`. `false` declares the dependency
@@ -494,6 +504,13 @@ export function publishesContentPages(config) {
  *                                   `itemCatalog: true` on the same entry,
  *                                   since a catalogue is fetched from the same
  *                                   index.
+ * @property {boolean} [assetReplacement]  Whether this dependency's asset
+ *                                   tree answers this package's own asset
+ *                                   addresses ahead of its local record.
+ *                                   Default `false`. Refuses `contentIndex:
+ *                                   false` on the same entry, since a
+ *                                   replacement with no fetched index to
+ *                                   check against resolves nothing.
  */
 
 /**
@@ -620,6 +637,9 @@ export function publishesContentPages(config) {
  * @property {string[]} [skipDirectories]   Directory names the content walk ignores
  *                                          wherever they appear (e.g. Obsidian's
  *                                          `Templates`). Default `[]`.
+ * @property {boolean} [forbidGeneratedArt]  Whether `lint` refuses an asset
+ *                                          record of this package carrying
+ *                                          `ai: true`. Default `false`.
  * @property {PackageBuildSection} [packageBuild]  Reserved for
  *                                          `@heroiclands/package-build`, which
  *                                          validates it. Not read here.
@@ -700,6 +720,8 @@ export function publishesContentPages(config) {
  *                                     types. The one set the compilers and the
  *                                     link-manifest emitter both read.
  * @property {readonly string[]} skipDirectories
+ * @property {boolean} forbidGeneratedArt  Whether `lint` refuses an asset
+ *                                     record of this package carrying `ai: true`.
  * @property {import("./engine/content-icons.mjs").IconRegistry} icons  The
  *                                     fonts this package ships and the names it
  *                                     draws from them; empty when it declares
@@ -728,6 +750,7 @@ const CONFIG_KEYS = [
     "itemBuilders",
     "paths",
     "skipDirectories",
+    "forbidGeneratedArt",
     "icons",
     "packs",
     "docs",
@@ -765,14 +788,25 @@ const PDF_FONT_KEYS = ["serif", "sans", "mono", "path"];
 const EMPTY_PDF_FONTS = Object.freeze({ serif: "", sans: "", mono: "", path: "" });
 const DOC_PAGE_KEYS = ["title", "out", "preamble", "frontmatter"];
 const RELATIONSHIP_KINDS = ["systems", "requires", "recommends", "conflicts"];
-const RELATIONSHIP_KEYS = [
+/**
+ * Every key a declared relationship may carry.
+ *
+ * Read by the manifest writer as well as by the configuration check: the keys
+ * Foundry's own relationship schema does not name are the build's own, and the
+ * published manifest carries none of them.
+ *
+ * @type {readonly string[]}
+ */
+export const RELATIONSHIP_KEYS = [
     "id",
     "contentPackage",
     "type",
     "manifest",
     "compatibility",
     "itemCatalog",
+    "assetArchive",
     "contentIndex",
+    "assetReplacement",
 ];
 const AUTHOR_KEYS = ["name", "email", "url"];
 const ITEM_BUILDER_KEYS = ["system", "img", "fields"];
@@ -2198,6 +2232,23 @@ function normalizeRelationships(value) {
                     }
                     spec.itemCatalog = rel.itemCatalog;
                 }
+                // Opt-in, sibling to `itemCatalog`: unpack this dependency's
+                // release archive for its asset bytes alone, building no item
+                // catalogue from it. Buys the archive for a package with no
+                // items of its own to extract — an asset-replacement source
+                // ships no Item packs and has no use for `itemCatalog: true`.
+                if (rel.assetArchive !== undefined) {
+                    if (typeof rel.assetArchive !== "boolean") {
+                        fail(`${at}.assetArchive`, "must be true or false");
+                    }
+                    if (rel.assetArchive && spec.manifest === undefined) {
+                        fail(
+                            `${at}.assetArchive`,
+                            "needs a `manifest` naming the package to fetch",
+                        );
+                    }
+                    spec.assetArchive = rel.assetArchive;
+                }
                 // Opt-out: declares the dependency for the Foundry manifest
                 // only, so `deps fetch` fetches no content index for it and a
                 // wikilink into it is refused rather than silently dead. A
@@ -2216,6 +2267,26 @@ function normalizeRelationships(value) {
                     }
                     spec.contentIndex = rel.contentIndex;
                 }
+                // Opt-in: this dependency's asset tree answers this
+                // package's own asset addresses ahead of its local record —
+                // the "rewrite table" `engine/asset-replacement.mjs` reads.
+                // A replacement with no fetched index to check against
+                // resolves nothing, so it cannot pair with
+                // `contentIndex: false`.
+                if (rel.assetReplacement !== undefined) {
+                    if (typeof rel.assetReplacement !== "boolean") {
+                        fail(`${at}.assetReplacement`, "must be true or false");
+                    }
+                    if (rel.assetReplacement && rel.contentIndex === false) {
+                        fail(
+                            `${at}.assetReplacement`,
+                            "cannot be true together with `contentIndex: false` — a " +
+                                "replacement with no fetched index to check against resolves " +
+                                "nothing",
+                        );
+                    }
+                    spec.assetReplacement = rel.assetReplacement;
+                }
                 return Object.freeze(spec);
             }),
         );
@@ -2694,6 +2765,12 @@ export function defineConfig(config) {
         requireNonEmptyString(name, `skipDirectories[${index}]`),
     );
 
+    const forbidGeneratedArt = optionalBoolean(
+        input.forbidGeneratedArt,
+        "forbidGeneratedArt",
+        false,
+    );
+
     // Refused above for a documentation package, so there is nothing to read
     // and nothing to derive an asset root or a package-wide system from.
     const foundryPackage =
@@ -2800,6 +2877,7 @@ export function defineConfig(config) {
         itemTypes,
         docEntryTypes,
         skipDirectories: Object.freeze(skipDirectories),
+        forbidGeneratedArt,
         icons: normalizeIcons(input.icons, rootDir),
         packs: Object.freeze(packs),
         packDirectories: Object.freeze(packDirectories),