@heroiclands/package-build 22.21.0 → 22.23.0

package/docs/configuration.md

@@ -55,7 +55,7 @@ around its own evaluation.
 
 ### Quick reference
 
-22 top-level keys. `rootDir` is not one of them — a data configuration never
+23 top-level keys. `rootDir` is not one of them — a data configuration never
 writes it — and is documented under [Derived values](#derived-values) instead,
 alongside `foundryPackage`, `homepage`, `author` and `itemBuilders`, whose
 data-configuration behaviour is also derivation rather than ordinary
@@ -72,6 +72,7 @@ authoring.
 | [`itemBuilders`](#itembuilders)             | object, or list of `{system, builders}` (or a name/list of names, in YAML) | no; refused in a `documentation` package                                                           | `{}`                      |
 | [`paths`](#paths)                           | object                                                                     | no                                                                                                 | see [`paths`](#paths)     |
 | [`skipDirectories`](#skipdirectories)       | string[]                                                                   | no                                                                                                 | `[]`                      |
+| [`forbidGeneratedArt`](#forbidgeneratedart) | boolean                                                                    | no                                                                                                 | `false`                   |
 | [`icons`](#icons)                           | object, or a path to a file holding one                                    | no                                                                                                 | empty registry            |
 | [`packs`](#packs)                           | array                                                                      | yes, at least one entry, in a `systems` or `modules` package; refused in a `documentation` package | —                         |
 | [`docs`](#docs)                             | object                                                                     | no; refused in a `documentation` package                                                           | `{}`                      |
@@ -87,7 +88,7 @@ authoring.
 
 Any key outside this list is refused:
 
-> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
+> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, forbidGeneratedArt, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
 
 (`rootDir` appears in that list because it is a key `defineConfig` itself
 accepts — an `.mjs` configuration authors it directly. A YAML configuration
@@ -515,7 +516,7 @@ HeroicLands layout, resolved against `rootDir`:
 | `paths.packJson`        | `build/packs-json`       | Build-only per-entry JSON intermediate.                                                         |
 | `paths.stage`           | `build/stage/packs`      | Compiled LevelDB packs.                                                                         |
 | `paths.unpack`          | `build/tmp/packs`        | Where `unpack` extracts JSON back to.                                                           |
-| `paths.foreignCache`    | `build/cache/foreign`    | Where a dependency declaring `itemCatalog: true` is unpacked.                                   |
+| `paths.foreignCache`    | `build/cache/foreign`    | Where a dependency declaring `itemCatalog: true` or `assetArchive: true` is unpacked.           |
 | `paths.metadataCache`   | `build/cache/metadata`   | Where a dependency's published content index is fetched to, for every declared dependency.      |
 | `paths.navigationCache` | `build/cache/navigation` | Where the site navigation heroiclands.org publishes is fetched to, for the generated Hugo menu. |
 
@@ -547,6 +548,26 @@ skipDirectories: [Templates]
 
 > ``package-build config: `skipDirectories[<index>]` must be a non-empty string.``
 
+### `forbidGeneratedArt`
+
+**Type:** boolean · **Optional** · default `false`.
+
+With it `true`, `package-build lint` refuses every asset record of this
+package whose `ai` field states `true` — a licensing stance, not a build
+detail: this package carries no machine-generated art. With it absent or
+`false`, `lint` reports nothing extra about an `ai: true` record.
+
+```yaml
+forbidGeneratedArt: true
+```
+
+`lint` reports a located error naming the record and its file for each one it
+finds:
+
+> ``<file>: error: `<address>` is machine-generated art (`ai: true`), and `forbidGeneratedArt` refuses it in this package``
+
+> ``package-build config: `forbidGeneratedArt` must be a boolean.``
+
 ### `icons`
 
 **Type:** object (`{families, icons, defaultFamily?}`), or a string naming a
@@ -1205,15 +1226,17 @@ system relationship it declares — see [`stats.systemVersion`](#statssystemvers
 
 Each entry, in any of the four lists:
 
-| Key (under `relationships.<kind>[]`)     | Type                            | Required | Default |
-| ---------------------------------------- | ------------------------------- | -------- | ------- |
-| `relationships.systems[].id`             | string                          | yes      | —       |
-| `relationships.systems[].contentPackage` | string                          | no       | the id  |
-| `relationships.systems[].type`           | string                          | no       | none    |
-| `relationships.systems[].manifest`       | string                          | no       | none    |
-| `relationships.systems[].compatibility`  | object, `{minimum?, verified?}` | no       | none    |
-| `relationships.systems[].itemCatalog`    | boolean                         | no       | `false` |
-| `relationships.systems[].contentIndex`   | boolean                         | no       | `true`  |
+| Key (under `relationships.<kind>[]`)       | Type                            | Required | Default |
+| ------------------------------------------ | ------------------------------- | -------- | ------- |
+| `relationships.systems[].id`               | string                          | yes      | —       |
+| `relationships.systems[].contentPackage`   | string                          | no       | the id  |
+| `relationships.systems[].type`             | string                          | no       | none    |
+| `relationships.systems[].manifest`         | string                          | no       | none    |
+| `relationships.systems[].compatibility`    | object, `{minimum?, verified?}` | no       | none    |
+| `relationships.systems[].itemCatalog`      | boolean                         | no       | `false` |
+| `relationships.systems[].assetArchive`     | boolean                         | no       | `false` |
+| `relationships.systems[].contentIndex`     | boolean                         | no       | `true`  |
+| `relationships.systems[].assetReplacement` | boolean                         | no       | `false` |
 
 (the same keys apply under `requires[]`, `recommends[]` and
 `conflicts[]`.)
@@ -1222,7 +1245,7 @@ Each entry, in any of the four lists:
 
 > ``package-build config: `relationships.<kind>[<index>].id` must be a non-empty string.``
 
-> ``package-build config: `relationships.<kind>[<index>].<key>` is not a recognized option (expected one of: id, contentPackage, type, manifest, compatibility, itemCatalog, contentIndex).``
+> ``package-build config: `relationships.<kind>[<index>].<key>` is not a recognized option (expected one of: id, contentPackage, type, manifest, compatibility, itemCatalog, assetArchive, contentIndex, assetReplacement).``
 
 `contentPackage` names what the other package's _content_ is called, where
 that differs from its Foundry id. A note addresses a file by the content
@@ -1241,6 +1264,31 @@ item catalogue at build time. It requires a `manifest`:
 
 > ``package-build config: `relationships.<kind>[<index>].itemCatalog` needs a `manifest` naming the package to fetch.``
 
+`assetArchive` opts into unpacking the named package's release archive for
+its asset bytes alone — the sibling of `itemCatalog`, for a dependency whose
+bytes are wanted and whose items are not. It builds no item catalogue from
+the archive, which is what distinguishes it from `itemCatalog: true`. It
+requires a `manifest`:
+
+> ``package-build config: `relationships.<kind>[<index>].assetArchive` must be true or false.``
+
+> ``package-build config: `relationships.<kind>[<index>].assetArchive` needs a `manifest` naming the package to fetch.``
+
+A relationship with no items of its own to extract, such as an asset
+replacement module, declares only `assetArchive: true`:
+
+```yaml
+relationships:
+  requires:
+    - id: thalornaaltart
+      manifest: https://…/releases/latest/download/module.json
+      compatibility: { verified: "1.0.0" }
+      assetArchive: true
+```
+
+A relationship declaring both `itemCatalog: true` and `assetArchive: true` is
+fetched once: `deps fetch` does not download the archive twice for one entry.
+
 `contentIndex` and `itemCatalog` are the two edges a relationship may declare,
 and a package may have either without the other. `itemCatalog` says a
 dependency supplies _items_; `contentIndex`, `true` by default, says
@@ -1260,6 +1308,35 @@ demand.
 
 > ``package-build config: `relationships.<kind>[<index>].contentIndex` cannot be false together with `itemCatalog: true` — a catalogue is fetched from the same index.``
 
+`assetReplacement` opts a relationship into serving this package's own asset
+addresses from the named dependency's tree instead of its local one —
+`engine/asset-replacement.mjs`'s `resolveAssetReplacement` is what reads the
+declaration. Off by default: declaring a dependency is not the same as
+wanting its pictures in place of the ones this package ships itself. It
+requires a fetched index to check the replacement against, so it cannot pair
+with `contentIndex: false`:
+
+```yaml
+relationships:
+  requires:
+    - id: thalornaaltart
+      manifest: https://…/releases/latest/download/module.json
+      assetReplacement: true
+      contentIndex: true
+```
+
+With that declared, an address `thalorna` would otherwise answer itself —
+`thalorna-none-image-thorn` — resolves against
+`thalornaaltart-none-image-thorn` first, falling back to `thalorna`'s own
+record when `thalornaaltart` carries no file at that address. A package
+declaring more than one `assetReplacement: true` relationship is tried in
+the order the relationships are declared, and the first one carrying the
+address wins.
+
+> ``package-build config: `relationships.<kind>[<index>].assetReplacement` must be true or false.``
+
+> ``package-build config: `relationships.<kind>[<index>].assetReplacement` cannot be true together with `contentIndex: false` — a replacement with no fetched index to check against resolves nothing.``
+
 ### `systems`
 
 **Type:** object (`{id: spec}`) · **Optional** · default `{}`. Refused in a
@@ -1462,6 +1539,7 @@ packageBuild:
 | [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                                              |
 | [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                                       |
 | [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.baseStyles`](#packagebuildbasestyles)                                       | boolean                                     | no       | `true`                                                     |
 | [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                                       |
 | [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                                     |
 | [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                                                       |
@@ -1475,7 +1553,7 @@ packageBuild:
 | [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8, rules: readability}` |
 | [`packageBuild.proseScore`](#packagebuildprosescore)                                       | object                                      | no       | `{minWords: 80, bands: {}}`                                |
 
-> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
+> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, baseStyles, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
 
 ### `packageBuild.proseLint`
 
@@ -1561,6 +1639,31 @@ repository has to compute. Neither declares anything, both default to
 
 > ``package-build config: `packageBuild.manifestFlags` must be a non-empty string.``
 
+### `packageBuild.baseStyles`
+
+Whether the package takes the shared base stylesheet. It defaults to `true`,
+is staged to `styles/package-build-base.css` under the stage root, and is
+named first in the generated manifest's `styles`.
+
+The sheet carries only what every package's compiled content relies on to be
+legible — the definition-list style an infobox and the markdown `Term` /
+`: definition` syntax both emit — and is scoped to the journal, enriched-field
+and editor containers so it cannot reach Foundry's own interface.
+
+It loads into the cascade layer Foundry reserves for the package kind,
+`system` or `modules`, which is the weakest layer a package can occupy. A
+package overrides any rule in it from its own stylesheet, whether that sheet
+names a layer or none at all, with no specificity contest and no
+`!important`. The term column, the gutter and the width at which the list
+stacks are custom properties — `--pb-deflist-term-width`,
+`--pb-deflist-gutter` and `--pb-deflist-row-gap` — so a package adjusts them
+without copying the rule.
+
+Declare `false` to decline it; nothing is staged and nothing is added to
+`styles`:
+
+> ``package-build config: `packageBuild.baseStyles` must be true or false.``
+
 ### `packageBuild.manifest`
 
 `packageBuild.manifest.title` is a required, non-empty string for a Foundry

package/docs/content-format.md

@@ -25,13 +25,15 @@ Start with [your first note](authoring/first-note.md). It explains the smallest
 
 A nonempty note body creates one system-agnostic Foundry JournalEntry. Content before the first H1 becomes an introduction page; every H1 starts another JournalEntryPage. A lower-level heading with an explicit `{#anchor}` starts a page too, so a link can address it. The same prose becomes a web page and can be selected for a book. The content index records the note and its frontmatter for queries and navigation.
 
-A `:::caption {#anchor}` fence labels the next prose, code, table, or image block. Its anchor makes the block addressable; `[[#anchor|]]` displays the generated kind and number, such as **Figure 12**. Foundry gives the captioned block a JournalEntryPage. See [captions and numbered references](authoring/links-and-markup.md#captions-and-numbered-references) for the syntax.
+A `:::figure {#anchor}` fence numbers whatever it holds — prose, code, a table, or an image. Its anchor makes the fence a target `{{ref "#anchor"}}` can point to, displaying the generated kind and number, such as **Figure 12**. Foundry gives the fence its own JournalEntryPage. See [figures and numbered references](authoring/links-and-markup.md#figures-and-numbered-references) for the syntax.
 
 Body extensions use braces with space-separated `key=value` attributes:
 `![[icon-harbor|Harbor]]{float=top-left size=medium}` and an SQL fence with
 `{allow-empty=true}` are examples. Inline font glyphs use the package's icon
 registry, as in `:icon warning:{size=lg}`; image icons use asset Addresses.
-`:::info` and `:::warn` add labelled boxes within the prose. The
+`:::info` and `:::warn` add labelled boxes within the prose. A
+`pagelist` fence renders the pages carrying a tag as a list of links, so a
+landing page states a group by intent rather than enumerating it. The
 [links and markup guide](authoring/links-and-markup.md) gives the complete syntax.
 Footnotes use `[^id]` references and `[^id]:` definitions, with numeric output
 markers scoped to each note. Definition lists use a term followed by one or

package/docs/guides/book.md

@@ -88,10 +88,11 @@ finding.
 Each section and each selected entry starts on its own page. The PDF has a
 contents page and an outline for section and entry navigation. A note's
 `description` appears as an epigraph when present. Wider tables span both
-columns; an uncaptioned wide table starts on a new page so it stays after its
-introduction. A captioned wide table may float to the page top, and its numbered
-caption stays with it. A table too tall for one page takes pages of its own.
-Caption numbers run through the whole book in reading order. Maps attached
+columns; a wide table outside a figure fence starts on a new page so it stays
+after its introduction. A wide table inside one may float to the page top, and
+its label stays with it. A table too tall for one page takes pages of its own.
+A figure's number runs through the whole book in reading order, counted within
+its own kind. Maps attached
 to selected places use landscape pages after those entries. Regional, theatre
 of the mind, battle, and local map backgrounds also print on landscape pages.
 Battle and local maps print each Scene level's background on its own page.

package/docs/guides/reference-pages.md

@@ -45,6 +45,21 @@ WHERE type = 'affiliation'
 ```
 ````
 
+Where the page introduces a _group_ rather than a type, a `pagelist` fence
+states the group by its tag and lists the pages carrying it:
+
+````markdown
+```pagelist {tag="key-concept" descriptions=true}
+
+```
+````
+
+That keeps the entry page true as notes are written: a page joins the list by
+carrying the tag, so nobody has to remember to add it here. A tag no page
+carries is a build error naming the tag. See
+[page lists](../authoring/links-and-markup.md#page-lists) for the attributes it
+takes.
+
 `data.pack: none` is appropriate when the page belongs on the site and in the
 index but does not need a Foundry compendium entry. A documentation package
 has no packs at all. A page with an empty body is a stub: it remains in the