@heroiclands/package-build 19.0.0 → 20.0.0

package/CONTENT.md

@@ -388,6 +388,24 @@ exactly once, here, and read through `loadPackConfig()` everywhere. There is one
 resolved set at runtime; the compilers and the link-manifest emitter cannot come
 to disagree about which notes carry documentation.
 
+**Every note compiling into a system-bearing document carries documentation, and
+that includes actors** (#337). `docEntryTypes` is `itemTypes` plus the actor
+types the shipped subtype maps declare (`ACTOR_TYPES`, derived from them rather
+than listed again), plus `macro` and the map types. Only `doc` is outside it, for
+the reason that actually applies to it: its single document _is_ the prose.
+
+A being therefore has the same two addresses an item has — `<pkg>-<system>-being-<shortcode>`
+for the Actor and `<pkg>-none-docbeing-<shortcode>` for the page — where before
+it had only the first, and was the one system-bearing note a prose link could not
+name.
+
+**An actor keeps its prose inline as well, and that asymmetry is deliberate.** An
+item's description is an `@UUID` pointer into its journal, because one item is
+embedded across hundreds of beings and baking long prose into every copy bloats
+the compendium by the length of the text times the number of carriers. An actor
+is singular, so the same indirection costs a reader a click and saves nothing:
+`system.appearance` and `system.dossier` stay as rendered prose.
+
 The Item compiler **dispatches through that same resolved table**, via
 `engine/item-registry.mjs` (`itemTypes()` and `itemBuilder(type)`), so the types a
 consumer's notes are accepted for and the builders they compile with are one
@@ -534,9 +552,46 @@ Both spellings are equal; the difference is only whether the type brings art.
 whitelist without a builder behind it.
 
 **The path is spelled the way a note spells it.** Registry art goes through the
-same `resolveImg` rule as a note's `img:`, so `icons/relic.svg` means _this_
-repository's asset root — `modules/sohl-relics/assets/icons/relic.svg` — and an
-already-served path (`systems/sohl/assets/icons/…`) passes through untouched.
+same `resolveImg` rule as a note's `img:`, so one spelling means one thing
+wherever it is written.
+
+#### An asset path's first segment says which package owns it
+
+Every authored asset path — a registry `img:`, a note's `img:`, an actor's
+`portrait:` — answers "which package holds this file?" in its **first segment**,
+and there are exactly three answers:
+
+| Authored path starts with | Owner                 | Emitted              |
+| ------------------------- | --------------------- | -------------------- |
+| `systems/`                | a separate **system** | unchanged            |
+| `modules/`                | a separate **module** | unchanged            |
+| anything else             | **this package**      | `<assetRoot>/<path>` |
+
+`assetRoot` is derived, never authored: it is
+`<packageKind>/<foundryPackage>/assets`, and it is the one place `systems/sohl`
+(or `modules/sohl-thalorna`) is ever spelled. So `icons/relic.svg` in a module's
+registry compiles to `modules/sohl-relics/assets/icons/relic.svg`, and the same
+string in the system's compiles to `systems/sohl/assets/icons/relic.svg`. An
+already-served `systems/sohl/assets/icons/…` passes through untouched — which is
+what lets a module pair a SoHL default with one of its own types.
+
+**"Anything else" is the rule, not a list of directories.** A package owns its
+whole `assets/` tree, so a directory this toolchain has never heard of is still
+that package's: art under `assets/artwork/` is addressed `artwork/deity.webp`
+and rooted exactly as `icons/…` and `images/…` are. An address naming no package
+at all — an absolute URL, a `data:` URI, a `/`-rooted path — passes through, on
+the same rule rather than as an exception.
+
+`worlds/` is deliberately not exempt: a package may not ship art out of a world,
+so prefixing such a path produces a plainly broken one rather than a plausible
+one that 404s in Foundry unreported.
+
+**`banner:` is a path that does not follow this rule.** It reaches no compiled
+document; it is a top-level key the Hugo theme reads, and the theme prefixes a
+relative value with `images/` and joins it onto `params.cdnBaseURL`. The two
+address different places — `img:` a file Foundry serves, `banner:` a file the
+CDN serves — so they are stated apart rather than reconciled. See the
+[content format specification](docs/content-format.md#banner-addresses-the-cdn-not-the-foundry-install).
 
 #### "Names no art" and "wants no art" are different (#218)
 
@@ -570,12 +625,20 @@ rather than two.
 > (`sohl/item-fields.mjs`, "the style of address the office carries"), so one
 > authored key fed two unrelated destinations that disagreed about what empty
 > means — and `title: null` stringified into the compiled document as the literal
-> `"null"`. That collision is gone: the field declares `topLevelMeans`, and the
-> top-level key is no longer a source for it (#218).
+> `"null"`. The field declares `topLevelMeans` now, so the top-level key is no
+> longer a source for it (#218).
+>
+> So `title: null` is a note declining to state a heading, and the site emitter's
+> `fm.title ?? name` falls back to `name.full`. `title: ""` publishes a
+> deliberately blank heading and is warned about on its own account — as the
+> page's heading, not as an art path.
 >
-> So `title: null` is now a note declining to state a heading, and the site
-> emitter's `fm.title ?? name` falls back to `name.full`. `title: ""` still
-> publishes a deliberately blank heading, and nothing warns about that yet.
+> **That warning reads the note's top level only.** The two spellings still name
+> unrelated quantities, so a `sohl.title` — the office's style of address — must
+> not answer for the page's heading. Twenty-eight `sohl-kethira-basic`
+> affiliations write `sohl.title: ""`, meaning an office with no style of
+> address, and every one of them was reported as publishing a blank heading
+> until the check honoured the declaration (#312).
 
 Because `""` used to mean "unset", a note still carrying that spelling has
 quietly changed meaning, and the frontmatter lint says so — for either art
@@ -712,6 +775,14 @@ state the same quantity, which is nearly everywhere: `subType` is the other
 declared item field spelled like a note-level key, and there the two agree by
 design.
 
+**The statement is symmetric, and the frontmatter linter reads it from the other
+side too.** If the two positions hold unrelated quantities, then the _in-block_
+position is not the note-level field either — so a check about a note-level field
+(the page's heading, an art path) reads past a block key the note's own type
+claims for something else. Declaring `topLevelMeans` settles both directions at
+once; it was read for the emitted field alone until #312, which is how an
+affiliation's office style came to answer for its page heading.
+
 **An exempted field is still authorable**, at the two positions that describe the
 document rather than the note:
 

package/bin/content-build.mjs

@@ -136,7 +136,7 @@ import {
     locateAddressFinding,
     addressFindingMessage,
 } from "../engine/address-diff.mjs";
-import { itemPackJsonDirs } from "../engine/generate.mjs";
+import { emittedArtFor, itemPackJsonDirs } from "../engine/generate.mjs";
 
 /**
  * The packs `unpack` extracts.
@@ -799,6 +799,12 @@ function lintCommand() {
                     // the compile asks the map for whichever pack it is
                     // writing, and a companion is a pack it writes.
                     packs: config.packDirectories,
+                    // What art each type actually reaches its document through,
+                    // asked of the passes rather than listed here (#349). This
+                    // is the one place that decides what a tree is held to, so
+                    // it is where the derivation is handed over — the linter
+                    // states no list of iconless types of its own.
+                    emittedArt: emittedArtFor,
                     references: argv.references,
                 });
 

package/content-config.mjs

@@ -69,6 +69,7 @@ import path from "node:path";
 // a cycle around a consumer's config file (see `engine/pack-config.mjs`).
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./engine/address-charset.mjs";
 import { MAP_TYPES, PACK_BY_TYPE } from "./engine/ids.mjs";
+import { ACTOR_TYPES } from "./engine/subtype-registry.mjs";
 import { NOTE_VOCABULARY } from "./engine/note-vocabulary.mjs";
 
 /**
@@ -1953,7 +1954,15 @@ export function defineConfig(config) {
     // holds every key any of them declares, so this stays "the registry's keys"
     // rather than becoming a second list to keep in step (#1504).
     const itemTypes = Object.freeze(new Set(Object.keys(itemBuilders)));
-    const docEntryTypes = Object.freeze(new Set([...itemTypes, "macro", ...MAP_TYPES]));
+    // Every note that compiles into a *system-bearing* document publishes its
+    // prose as a documentation JournalEntry, and that includes actors (#337).
+    // A being was the one such note with no `none` address — its only address
+    // named the Actor — so nothing a prose link wrote could land on its page.
+    // `doc` stays out for the reason that actually applies to it: its single
+    // document *is* the prose.
+    const docEntryTypes = Object.freeze(
+        new Set([...itemTypes, ...ACTOR_TYPES, "macro", ...MAP_TYPES]),
+    );
 
     return Object.freeze({
         rootDir,