@heroiclands/package-build 22.28.0 → 23.0.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @heroiclands/package-build
 
+## 23.0.0
+
+### Major Changes
+
+Every page a work of literature names in its subjects lists that work under **In song and story**, with its form beside the title, including works from a package this one depends on.
+
+### Patch Changes
+
+Affiliations, skills, attributes, mysteries, mystical abilities and miscellaneous gear without their own art show SoHL's default icons again instead of a broken image.
+
+Folder notes need only a nonempty body: a short line or placeholder no longer warns or fails, with or without `draft`. An empty folder body is still an error.
+
+Lore notes can be typed `literature` for epics, sagas, poems, legends and other works a people tells, sings or writes. A literature note may name its people, its form, its subjects and its language, and each appears in the note's infobox, with the people, subjects and language as links.
+
 ## 22.28.0
 
 ### Minor Changes

package/docs/api.md

@@ -471,7 +471,7 @@ What a draft note says about itself, in one sentence, on every surface it reache
 
 ### `engine.stubLint`
 
-Every typed note must have a nonempty body. Empty and whitespace-only bodies are errors regardless of description or `draft` tag, including structural types such as `folder` and `homepage`. Placeholder-only bodies also produce errors. Nonempty bodies with fewer than 25 prose words produce warnings unless tagged `draft`. Untyped vault scaffolding is excluded. The lint, content-index, package compile, site and PDF commands enforce body errors before publishing. The state classification helpers still describe incomplete records for inspection; their classifications do not exempt notes from validation.
+Every typed note must have a nonempty body. Empty and whitespace-only bodies are errors regardless of description or `draft` tag, including structural types such as `folder` and `homepage`. Placeholder-only bodies also produce errors. Nonempty bodies with fewer than 25 prose words produce warnings unless tagged `draft`. A `folder` note is held only to the nonempty rule: any body, placeholder or short, passes with or without `draft`. Untyped vault scaffolding is excluded. The lint, content-index, package compile, site and PDF commands enforce body errors before publishing. The state classification helpers still describe incomplete records for inspection; their classifications do not exempt notes from validation.
 
 | Export             | Signature                                                  | Returns                                             | Use it when                                                                                   |
 | ------------------ | ---------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------- |

package/docs/authoring/first-note.md

@@ -45,4 +45,4 @@ The full Address is `<package>-note-lore-harbor`; `<package>` comes from `conten
 
 Add `description` for a short page summary, `tags: [draft]` to mark unfinished prose, or `data` for fields the note's type permits. A system block such as `sohl:` or `hm3:` adds mechanics and can produce a Foundry Actor or Item. It does not replace the shared prose or make another JournalEntry. [Frontmatter](frontmatter.md) explains the allowed keys, and the [note-type reference](../reference/note-types.md) lists every type-specific field.
 
-Every typed note must have a nonempty body after its frontmatter. An empty or whitespace-only body is an error, even with `tags: [draft]` or a description. This includes folder and homepage notes. A nonempty body with fewer than 25 prose words produces a warning unless the note has a `draft` tag. See [note states](../reference/format-details.md#three-states-of-a-note).
+Every typed note must have a nonempty body after its frontmatter. An empty or whitespace-only body is an error, even with `tags: [draft]` or a description. This includes folder and homepage notes. A nonempty body with fewer than 25 prose words produces a warning unless the note has a `draft` tag. A folder note needs only a nonempty body: any content passes, with or without the tag. See [note states](../reference/format-details.md#three-states-of-a-note).

package/docs/content-format.md

@@ -9,7 +9,7 @@ subType: userguide
 
 A content package begins with Markdown notes under `assets/content/`. Each note has YAML frontmatter describing its identity and data, followed by prose. Folder names beneath `assets/content/` are for authors; `type`, `subType`, and Addresses determine what the build creates.
 
-Every typed note requires a nonempty body, including drafts, folders and homepages. An empty or whitespace-only body is an error. A nonempty body with fewer than 25 prose words warns unless tagged `draft`; the tag never exempts an empty body.
+Every typed note requires a nonempty body, including drafts, folders and homepages. An empty or whitespace-only body is an error. A nonempty body with fewer than 25 prose words warns unless tagged `draft`; the tag never exempts an empty body. A `folder` note needs only a nonempty body: any content passes, with or without `draft`.
 
 Start with [your first note](authoring/first-note.md). It explains the smallest valid note and shows the JournalEntry, web page, book entry, and content-index record made from it. Then use the chapters below in the order your note needs them.
 

package/docs/guides/site.md

@@ -144,12 +144,12 @@ The build always writes `title`, `slug`, `url`, `kbfolder`, `package` and
 note. `infoboxes` is assembled from the note's own fields, so no note authors
 it and nothing in the note format accepts it.
 
-The build writes `resolvedDates`, `related`, `contains`, `governed_by`, `governed_places`
-and `map` only when it has something to write. A page with no links either way
+The build writes `resolvedDates`, `related`, `contains`, `governed_by`, `governed_places`,
+`works` and `map` only when it has something to write. A page with no links either way
 carries no `related`, and a place with no drawing carries no `map`.
 
-An authored `aliases`, `related`, `contains`, `governed_by`, `governed_places` or `map` is
-dropped. Each states a fact about the whole tree rather than about one note, so
+An authored `aliases`, `related`, `contains`, `governed_by`, `governed_places`, `works` or
+`map` is dropped. Each states a fact about the whole tree rather than about one note, so
 the build replaces whatever a note wrote.
 
 Artwork addresses are rewritten in place under `data`. A page's `data.icon`,

package/docs/reference/format-details.md

@@ -837,7 +837,7 @@ and the whole of it is the suffix.
 
 ```markdown
 ![A map of the Vale](images/maps/valeofthorns.webp) <!-- this package's -->
-![A shield](sohl/assets/icons/noun/shield.svg) <!-- the sohl package's -->
+![A shield](sohl/assets/icons/noun/shieldnn.svg) <!-- the sohl package's -->
 ```
 
 The four forms, for a `harnensemble` note (the `harnensemble` content package
@@ -850,14 +850,14 @@ ships as the Foundry module `harn-ensemble`) writing `images/map.webp`:
 | **Web**     | `https://cdn.heroiclands.org/harnensemble/images/map.webp` |
 | **Book**    | `assets/images/map.webp`, staged beside the Typst source   |
 
-And for the same note writing `sohl/assets/icons/noun/shield.svg`, a file the
+And for the same note writing `sohl/assets/icons/noun/shieldnn.svg`, a file the
 system ships and this repository does not hold:
 
 | Surface     | Address                                                       |
 | ----------- | ------------------------------------------------------------- |
-| **Foundry** | `systems/sohl/assets/icons/noun/shield.svg`                   |
-| **Local**   | `assets/icons/noun/shield.svg`, in the `sohl` repository      |
-| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shield.svg`      |
+| **Foundry** | `systems/sohl/assets/icons/noun/shieldnn.svg`                 |
+| **Local**   | `assets/icons/noun/shieldnn.svg`, in the `sohl` repository    |
+| **Web**     | `https://cdn.heroiclands.org/sohl/icons/noun/shieldnn.svg`    |
 | **Book**    | not carried, unless a declared replacement carries it instead |
 
 **The content package name and Foundry id are separate values.**
@@ -2010,7 +2010,9 @@ Every typed note requires a nonempty body after its closing frontmatter fence.
 An empty or whitespace-only body is an error, regardless of description or
 `tags: [draft]`. This includes `folder` and `homepage` notes. Untyped vault
 scaffolding is excluded. A nonempty body with fewer than 25 prose words warns
-unless tagged `draft`; the tag never exempts an empty body.
+unless tagged `draft`; the tag never exempts an empty body. A `folder` note is
+held only to the nonempty rule: any body, a placeholder or a single line
+included, passes with or without `draft`.
 
 The `lint`, `content-index`, `package compile`, `site` and `pdf` commands enforce
 body errors. Write a short beginning and tag it `draft` when work is unfinished.
@@ -2055,7 +2057,7 @@ same.
 | A lone heading          | no     | The same                                                        |
 | `_To be written._`      | no     | The same                                                        |
 
-An HTML comment is deliberately not empty, but an invisible marker does not supply prose. Replace placeholder-only content with written text.
+An HTML comment is deliberately not empty, but an invisible marker does not supply prose. Replace placeholder-only content with written text. A `folder` note is the exception: any of these bodies satisfies it, and the lint reports nothing.
 
 #### What a stub emits
 
@@ -2794,6 +2796,15 @@ An Item can mark its readable description with `# ... {#description}`. That head
 
 Generates a living (or undead, or spirit) being.
 
+**subType**:
+
+- npc: A character meant to be encountered. It may describe a reusable template and need not be
+  a singular individual.
+- character: A detailed, playable, singular individual.
+- creature: Any being that is neither a character nor an NPC.
+
+See [a being's subtype describes the subject](#a-beings-subtype-describes-the-subject).
+
 | `data` property             | Values                                         | Description                                                                                                                                           |
 | --------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `tokenIcon`                 | `Address`                                      | What a token on the canvas wears — an `icon` address; defaults to `icon`                                                                              |
@@ -3926,22 +3937,39 @@ the setting itself, rather than instructions or other apparatus for the GM.
   which covers the _reckoning_ — a festival's date is calendar and the festival is not, and a
   tournament is not a matter of time-reckoning at all — and from `culture`, which is a grouping
   of people rather than an occasion they attend.
-
-| `data` property         | Values                                                                        | Description                                                                         |
-| ----------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `epoch`                 | canonical `<year>.<day>`                                                      | The canonical day that equals calendar year 1, day 1                                |
-| `months`                | `{ name, abbreviation?, days }[]`                                             | Ordered months; their days sum to the world's year                                  |
-| `weekdays`              | `{ name, abbreviation? }[]`                                                   | Ordered week days, indexed from zero; weeks run continuously                        |
-| `seasons`               | `{ name, abbreviation?, start }[]`                                            | Seasons starting on one-based days of year                                          |
-| `namedDays`             | `{ name, abbreviation?, day }[]`                                              | Names assigned to one-based days of year                                            |
-| `eras`                  | `{ shortcode, name, abbreviation?, marker?, proclaimedBy?, start, label? }[]` | Year counts; `start` is `null` or an in-calendar year                               |
-| `formats`               | map of names to Calendaria patterns                                           | Named date formats; `std` is the preferred default                                  |
-| `events`                | `{ when, until?, recurs? }[]`                                                 | This note's dated occurrences, each with its own relationships and chronicle fields |
-| `events[].when`         | a date, or `"0.<day>"`                                                        | The occurrence's anchor and first instance — required                               |
-| `events[].until`        | a date                                                                        | Where the occurrence ran to, or where a recurring series stopped                    |
-| `events[].recurs`       | `{ every }` or `{ on }`                                                       | How further occurrences are found, absent for a one-time occurrence                 |
-| `events[].recurs.every` | whole number of years, 1 or more                                              | A period counted on the canonical axis from `when`                                  |
-| `events[].recurs.on`    | list of dates, strictly increasing, each later than `when`                    | Recorded occurrences beyond the first, in place of a period                         |
+- literature: A work a people composes and keeps — an epic, saga, poem, legend, hymn or
+  chronicle, told, sung or written. Held apart from `history`, which states what happened: a
+  legend is literature whether or not its events took place, and a chronicle is literature as a
+  work even where its events are also history.
+
+Each note a work names in `data.subjects` lists that work on its own site page, under **In
+song and story**, with the work's `form` beside its title; the subject note writes nothing.
+A work in a fetched index lists on this package's pages when that index carries its
+`subjects`.
+
+Calendar fields are written only on a `calendar` note, and `culture`, `form`, `subjects` and
+`language` only on a `literature` note; written on any other lore subType, each is an error at
+its own key.
+
+| `data` property         | Values                                                                        | Description                                                                                                       |
+| ----------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `epoch`                 | canonical `<year>.<day>`                                                      | The canonical day that equals calendar year 1, day 1                                                              |
+| `months`                | `{ name, abbreviation?, days }[]`                                             | Ordered months; their days sum to the world's year                                                                |
+| `weekdays`              | `{ name, abbreviation? }[]`                                                   | Ordered week days, indexed from zero; weeks run continuously                                                      |
+| `seasons`               | `{ name, abbreviation?, start }[]`                                            | Seasons starting on one-based days of year                                                                        |
+| `namedDays`             | `{ name, abbreviation?, day }[]`                                              | Names assigned to one-based days of year                                                                          |
+| `eras`                  | `{ shortcode, name, abbreviation?, marker?, proclaimedBy?, start, label? }[]` | Year counts; `start` is `null` or an in-calendar year                                                             |
+| `formats`               | map of names to Calendaria patterns                                           | Named date formats; `std` is the preferred default                                                                |
+| `culture`               | `Address`                                                                     | `literature` only: the people whose work it is, naming a lore note with `subType: culture`                        |
+| `form`                  | `string`                                                                      | `literature` only: the kind of work in its people's own terms — `epic`, `saga`, `praise-song`, `elegy`. Free text |
+| `subjects`              | `Address[]`                                                                   | `literature` only: the beings, places, gods, events and other notes the work concerns                             |
+| `language`              | `Address`                                                                     | `literature` only: the tongue it is composed in, naming a skill note with `subType: language`                     |
+| `events`                | `{ when, until?, recurs? }[]`                                                 | This note's dated occurrences, each with its own relationships and chronicle fields                               |
+| `events[].when`         | a date, or `"0.<day>"`                                                        | The occurrence's anchor and first instance — required                                                             |
+| `events[].until`        | a date                                                                        | Where the occurrence ran to, or where a recurring series stopped                                                  |
+| `events[].recurs`       | `{ every }` or `{ on }`                                                       | How further occurrences are found, absent for a one-time occurrence                                               |
+| `events[].recurs.every` | whole number of years, 1 or more                                              | A period counted on the canonical axis from `when`                                                                |
+| `events[].recurs.on`    | list of dates, strictly increasing, each later than `when`                    | Recorded occurrences beyond the first, in place of a period                                                       |
 
 `data.events` is available on every `lore` subType. Each entry's `kind`, `depth`, `summary`, `sources`, `standing`, `accounts`, `who`, `where`, `unresolved`, `follows` and `names` hold its chronicle detail; their shapes belong to whatever design governs chronicle records, and this format only asks that they sit inside an entry. The shared format checks `when`, `until` and `recurs`; a content package can check the rest. `events` itself does not appear as an infobox row, but a recurring entry's computed next occurrence does.
 

package/docs/reference/note-types.md

@@ -417,7 +417,7 @@ These fields are accepted by every note type. A field's value can still be irrel
 
 ### lore
 
-**Subtypes:** `cosmology`, `deity`, `theology`, `arcana`, `spirit`, `economy`, `law`, `calendar`, `history`, `material`, `folk`, `culture`, `custom`, `bestiary`, `gathering`.
+**Subtypes:** `cosmology`, `deity`, `theology`, `arcana`, `spirit`, `economy`, `law`, `calendar`, `history`, `material`, `folk`, `culture`, `custom`, `bestiary`, `gathering`, `literature`.
 
 Lore records in-world knowledge. A `culture` describes a people; a `custom` describes how they practice a rite, observance, or usage. A `material` describes a physical constituent and its qualities, which may vary by region. See the [lore subtype definitions](format-details.md#type-lore) for the complete vocabulary.
 
@@ -430,6 +430,10 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 | `data.namedDays` | list of `{ name, abbreviation?, day }`                                              | Names assigned to particular days of the year.                                                                                       |
 | `data.eras`      | list of `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, label? }` | The year-counts kept in this calendar. A marker names one era and uses these months.                                                 |
 | `data.formats`   | map of named Calendaria format strings                                              | Named patterns for reading and writing this calendar's dates.                                                                        |
+| `data.culture`   | an Address                                                                          | The people whose work this is, as a culture lore note.                                                                               |
+| `data.form`      | string                                                                              | The kind of work in its people's own terms — an epic, a saga, a praise-song, an elegy. Free text.                                    |
+| `data.subjects`  | list of Addresses                                                                   | The beings, places, gods, events and other notes the work concerns.                                                                  |
+| `data.language`  | an Address                                                                          | The tongue the work is composed in, as a language skill note.                                                                        |
 | `data.events`    | list of `{ when, until?, recurs? }`                                                 | This note's dated occurrences — a founding once, an anniversary that recurs, or a list of recorded happenings.                       |
 
 ### map

package/docs/reference/theme-pages.md

@@ -14,7 +14,7 @@ map, search, and the markup an image or a figure renders as — and names the
 classes a consumer styles against.
 
 **None of the sections below is an authoring instruction.** `infoboxes`,
-`related`, `contains`, `governed_by`, `governed_places`, `map`, `package`, `slug`, `url`
+`related`, `contains`, `governed_by`, `governed_places`, `works`, `map`, `package`, `slug`, `url`
 and `title` cannot be written by a note at all: a note's top-level region is
 closed and does not admit them, so each arrives already resolved by the time
 the theme sees it. Read this page when a panel is missing or a class needs
@@ -215,6 +215,37 @@ uses, so a region with forty settlements stays scannable.
 A page whose front matter declares none of `contains`, `governed_by` or
 `governed_places` renders no card at all.
 
+## The "In song and story" card
+
+`partials/literature-works.html` renders a second card directly below the
+government card, listing the works of literature that name the page's subject.
+The build derives `works` from every `literature` lore note's `data.subjects`,
+including works a fetched index carries, so no note writes it:
+
+```yaml
+---
+works: [{ title: …, url: …, form: … }] # works naming this page, sorted by title
+---
+```
+
+`form` is the work's `data.form`, printed in parentheses beside its title, and is
+absent when the work states none. A work naming one subject twice lists once, and
+a work naming itself is not listed on its own page. An entry's `url` is absent
+for a work that publishes no page, which renders as plain text through
+`partials/holdings/entry.html`. A page no work names carries no `works` and
+renders no card.
+
+The card reuses the government card's classes, so a consumer styling one styles
+both; `.literature-works` on the `<section>` tells them apart.
+
+| class                   | drawn as                          |
+| ----------------------- | --------------------------------- |
+| `.literature-works`     | the card, beside `.holdings`      |
+| `.holdings-table-label` | "In song and story"               |
+| `.holdings-table-grid`  | the grid of works                 |
+| `.holdings-entry-name`  | a work's title, linked or plain   |
+| `.holdings-entry-kind`  | the work's form, beside its title |
+
 ## The place map
 
 A place page with `map: from-<shortcode>.svg` displays a **From here** panel

package/engine/content-format.yaml

@@ -241,6 +241,10 @@ types:
             - namedDays
             - eras
             - formats
+            - culture
+            - form
+            - subjects
+            - language
             - events
         subTypes:
             - cosmology
@@ -258,6 +262,7 @@ types:
             - custom
             - bestiary
             - gathering
+            - literature
     map:
         data:
             - scene

package/engine/literature-notes.mjs

@@ -0,0 +1,133 @@
+/*
+ * 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
+ */
+
+/**
+ * A work a people tells, sings or writes: the `literature` lore subType and the
+ * four optional facts such a note may state about itself.
+ *
+ * `DataFieldSpec` declares the keys a type accepts, not the subType that may
+ * write them, so {@link checkLiteratureNote} scopes these keys to `literature`
+ * the way the calendar check scopes its own to `calendar`.
+ *
+ * @module
+ */
+
+import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
+import { checkCultureChoice } from "./culture-choice.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/** The `lore` subType whose notes are works of literature. */
+export const LITERATURE_SUBTYPE = "literature";
+
+/**
+ * Require `data.language` to address a `skill` note whose subType is
+ * `language`.
+ *
+ * An Address that does not resolve is the reference check's to report, so
+ * this speaks only about a target that exists and is the wrong kind.
+ *
+ * @param {object} note
+ * @param {{index?: object}} [options]
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageChoice(note, { index } = {}) {
+    const value = note.fm?.data?.language;
+    if (value === undefined || value === null || !index?.addressHit) return [];
+    const tuple = parseAddress(value, {
+        package: index.contentPackage,
+        system: "note",
+        type: "skill",
+        types: index.types,
+        packages: index.packages,
+    });
+    if (tuple.reason) return [];
+    const target = index.addressHit(renderAddress(tuple));
+    if (!target) return [];
+    const fm = target.fm ?? target;
+    if (tuple.type === "skill" && fm.subType === "language") return [];
+    return [
+        {
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", ["data", "language"]),
+            severity: "error",
+            message: `data.language ${isAddressTuple(value) ? renderAddress(value) : value} names a note that is not a skill whose subType is language`,
+        },
+    ];
+}
+
+/**
+ * The fields a `literature` note may state. Every one is optional.
+ *
+ * @type {ReadonlyArray<object>}
+ */
+export const LITERATURE_FIELDS = Object.freeze([
+    {
+        name: "culture",
+        shape: "an Address",
+        kind: "address",
+        ref: "lore",
+        accepts: ["lore"],
+        check: checkCultureChoice,
+        describe: "The people whose work this is, as a culture lore note.",
+    },
+    {
+        name: "form",
+        shape: "string",
+        kind: "string",
+        describe:
+            "The kind of work in its people's own terms — an epic, a saga, a " +
+            "praise-song, an elegy. Free text.",
+    },
+    {
+        name: "subjects",
+        shape: "list of Addresses",
+        kind: "list",
+        entryKind: "address",
+        describe: "The beings, places, gods, events and other notes the work concerns.",
+    },
+    {
+        name: "language",
+        shape: "an Address",
+        kind: "address",
+        ref: "skill",
+        accepts: ["skill"],
+        check: checkLanguageChoice,
+        describe: "The tongue the work is composed in, as a language skill note.",
+    },
+]);
+
+const LITERATURE_KEYS = Object.freeze(LITERATURE_FIELDS.map((field) => field.name));
+
+/**
+ * Refuse a literature field on a lore note of any other subType.
+ *
+ * @param {object} note
+ * @returns {object[]} One error per literature key written off `literature`.
+ */
+export function checkLiteratureNote(note) {
+    const type = String(note?.type ?? note?.fm?.type ?? "").toLowerCase();
+    const subType = String(note?.fm?.subType ?? "").toLowerCase();
+    if (type !== "lore" || subType === LITERATURE_SUBTYPE) return [];
+    const data = note?.fm?.data;
+    if (!data || typeof data !== "object" || Array.isArray(data)) return [];
+    return LITERATURE_KEYS.filter((key) => data[key] !== undefined && data[key] !== null).map(
+        (key) => ({
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", ["data", key], { key: true }),
+            severity: "error",
+            message:
+                `\`data.${key}\` describes a work of literature, and this note's ` +
+                `\`subType\` is not \`literature\``,
+        }),
+    );
+}

package/engine/literature-works.mjs

@@ -0,0 +1,153 @@
+/*
+ * 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
+ */
+
+/**
+ * The works of literature that concern each page, derived from what the works
+ * say. A `literature` lore note names its subjects in `data.subjects`; the site
+ * build inverts that into a `works` list on every subject's page, so a reader on
+ * a hero's, a place's or a god's page reaches the epics and legends about it.
+ * The subject note writes nothing.
+ *
+ * A work in a fetched index lists on this package's subject pages when that
+ * index carries its `subjects`. A subject in another package has no page here,
+ * so a local work naming one lists nowhere.
+ *
+ * @module
+ */
+
+import { parseAddress, renderAddress } from "./address.mjs";
+import { readCanonicalKey } from "./content-address.mjs";
+import { LITERATURE_SUBTYPE } from "./literature-notes.mjs";
+
+/** The page front-matter key the site build writes. */
+export const WORKS_KEY = "works";
+
+/** @typedef {{title: string, url?: string, form?: string}} WorkEntry */
+/**
+ * @typedef {object} WorksNode
+ * @property {string} key Own Address, normalized to the `note` system.
+ * @property {string} title
+ * @property {string} [url] Absent for a note that publishes no page.
+ * @property {string} [package] Owning content package.
+ * @property {string} [form] A work's `data.form`.
+ * @property {unknown[]} subjects A work's `data.subjects`; empty for any other note.
+ */
+
+/** The note-system key of one Address, or "" where it names nothing. */
+function addressKey(value, pkg, types) {
+    if (value == null) return "";
+    const tuple = parseAddress(value, { package: pkg ?? "local", system: "note", types });
+    if (tuple.reason) return "";
+    return renderAddress({ ...tuple, system: "note" }).toLowerCase();
+}
+
+/** Whether a note is a work of literature. */
+function isWork(type, subType) {
+    return type === "lore" && String(subType ?? "").toLowerCase() === LITERATURE_SUBTYPE;
+}
+
+/**
+ * One local page's node.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {{title: string, url?: string, package?: string}} page
+ * @returns {WorksNode|null} Null for a note with no type or shortcode.
+ */
+export function worksNode(fm, { title, url, package: pkg }) {
+    const type = String(fm?.type ?? "");
+    const shortcode = String(fm?.shortcode ?? "").toLowerCase();
+    if (!type || !shortcode) return null;
+    const data = fm.data && typeof fm.data === "object" && !Array.isArray(fm.data) ? fm.data : {};
+    const work = isWork(type, fm.subType);
+    return {
+        key: renderAddress({ package: pkg ?? "local", system: "note", type, shortcode }),
+        title,
+        ...(url ? { url } : {}),
+        ...(pkg ? { package: pkg } : {}),
+        ...(work && typeof data.form === "string" && data.form ? { form: data.form } : {}),
+        subjects:
+            !work ? []
+            : Array.isArray(data.subjects) ? data.subjects
+            : data.subjects ? [data.subjects]
+            : [],
+    };
+}
+
+/**
+ * The works a fetched index carries, as nodes. Only a work can list itself on
+ * a page, and only a page of this package can carry the list, so a foreign
+ * entry that is not a work is never needed here.
+ *
+ * @param {Map<string, object>|undefined} foreignIndex
+ * @returns {WorksNode[]}
+ */
+export function foreignWorksNodes(foreignIndex) {
+    const out = [];
+    for (const [canonical, entry] of foreignIndex ?? []) {
+        const tuple = readCanonicalKey(canonical);
+        if (!tuple || !isWork(entry?.type, entry?.subType)) continue;
+        if (!Array.isArray(entry.subjects) || !entry.subjects.length) continue;
+        out.push({
+            key: renderAddress({ ...tuple, system: "note" }),
+            title: String(entry.name ?? tuple.shortcode),
+            ...(entry.url ? { url: entry.url } : {}),
+            package: tuple.package,
+            ...(typeof entry.form === "string" && entry.form ? { form: entry.form } : {}),
+            subjects: entry.subjects,
+        });
+    }
+    return out;
+}
+
+/**
+ * Invert every work's subjects into the list each subject's page carries.
+ *
+ * A subject is resolved in its work's own package. A work naming one subject
+ * twice lists once; a work naming itself is not listed on its own page.
+ * Entries sort by title.
+ *
+ * @param {Iterable<WorksNode|null>} nodes - Every local page, then any foreign work.
+ * @param {object} options
+ * @param {ReadonlySet<string>} options.types - Note types an Address may name.
+ * @returns {Map<string, {works: WorkEntry[]}>} Keyed by the subject page's URL.
+ */
+export function worksPages(nodes, { types }) {
+    const all = [...nodes].filter(Boolean);
+    /** @type {Map<string, WorksNode>} */
+    const pages = new Map();
+    for (const node of all) {
+        if (!node.url) continue;
+        const key = node.key.toLowerCase();
+        if (!pages.has(key)) pages.set(key, node);
+    }
+    /** @type {Map<string, {works: WorkEntry[]}>} */
+    const lists = new Map();
+    for (const work of all) {
+        const seen = new Set();
+        for (const subject of work.subjects) {
+            const target = pages.get(addressKey(subject, work.package, types));
+            if (!target || target.key === work.key || seen.has(target.url)) continue;
+            seen.add(target.url);
+            let block = lists.get(target.url);
+            if (!block) lists.set(target.url, (block = { works: [] }));
+            block.works.push({
+                title: work.title,
+                ...(work.url ? { url: work.url } : {}),
+                ...(work.form ? { form: work.form } : {}),
+            });
+        }
+    }
+    for (const block of lists.values())
+        block.works.sort((a, b) => a.title.localeCompare(b.title, "en"));
+    return lists;
+}

package/engine/metadata-index.mjs

@@ -437,6 +437,14 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 ...(Object.hasOwn(record.data ?? {}, "government") ?
                     { government: record.data.government }
                 :   {}),
+                // What a work of literature concerns and what kind of work it
+                // is, so a consumer's subject pages list a dependency's works.
+                ...(parts.type === "lore" && record.subType === "literature" ?
+                    {
+                        subjects: record.data?.subjects ?? undefined,
+                        form: record.data?.form ?? undefined,
+                    }
+                :   {}),
                 package: pkg,
             });
             const entry = index.get(key);

package/engine/note-vocabulary.mjs

@@ -109,6 +109,7 @@ import { checkAffiliationRankFloor, checkRankLadder } from "./rank-ladder.mjs";
 import { checkCalendarChoice } from "./calendar-choice.mjs";
 import { checkLoreEvents } from "./lore-events.mjs";
 import { checkCultureChoice } from "./culture-choice.mjs";
+import { LITERATURE_FIELDS, checkLiteratureNote } from "./literature-notes.mjs";
 import { SOCIAL_TIES, SOCIAL_TIE_TARGET_TYPES } from "./social-tie-terms.mjs";
 import { parseNoteDate } from "./note-dates.mjs";
 import { reckoningContext } from "./reckoning-markers.mjs";
@@ -1479,15 +1480,21 @@ export const NOTE_VOCABULARY = Object.freeze({
             "custom", // How a people practices a rite, observance, or usage.
             "bestiary", // A kind of creature that is not a people.
             "gathering", // A recurring public assembly, such as a fair or tournament.
+            "literature", // A work a people tells, sings, or writes, such as an epic or legend.
         ]),
         // A lore note is prose, and what it *is* about is its subType — with
-        // one exception. A calendar is a division of the year, and a division
-        // is data; the check scopes the family to the subType that means it,
-        // because `DataFieldSpec` declares the keys a type accepts and not the
-        // subType that may write them.
-        check: checkCalendarNote,
+        // two exceptions. A calendar is a division of the year, and a division
+        // is data; a work of literature states whose it is, in what tongue and
+        // about what. The checks scope each family to the subType that means
+        // it, because `DataFieldSpec` declares the keys a type accepts and not
+        // the subType that may write them.
+        check: (note, context) => [
+            ...checkCalendarNote(note, context),
+            ...checkLiteratureNote(note),
+        ],
         data: Object.freeze([
             ...CALENDAR_FIELDS,
+            ...LITERATURE_FIELDS,
             {
                 name: "events",
                 kind: "list",

package/engine/site-build.mjs

@@ -95,7 +95,7 @@ import { resolvedDateFields } from "./note-dates.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 // The one statement of what an empty body means, shared with the index.
 import { isStubNote } from "./note-state.mjs";
-import { isGmNote } from "./note-vocabulary.mjs";
+import { NOTE_VOCABULARY, isGmNote } from "./note-vocabulary.mjs";
 import { ART_SLOTS, artPathname, assetAddressIndex, pathnameRoles } from "./art-fields.mjs";
 import { embedRole } from "./content-embeds.mjs";
 import {
@@ -109,6 +109,7 @@ import { publishesContentPages } from "../content-config.mjs";
 import { HUGO_CONTENT } from "./site-config.mjs";
 import { homepageLinkTargets, relatedPages } from "./related-pages.mjs";
 import { HOLDINGS_KEYS, foreignHoldingsNodes, holdingsNode, holdingsPages } from "./holdings.mjs";
+import { WORKS_KEY, foreignWorksNodes, worksNode, worksPages } from "./literature-works.mjs";
 import { drawSiteMaps } from "./site-maps.mjs";
 
 const require = createRequire(import.meta.url);
@@ -607,6 +608,7 @@ export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
     delete data.aliases;
     delete data.related;
     for (const key of HOLDINGS_KEYS) delete data[key];
+    delete data[WORKS_KEY];
     delete data.map;
     if (webSrc && artSrc) resolveArtFields(data, webSrc, artSrc);
     return data;
@@ -1089,12 +1091,25 @@ export function renderPages(pages, options) {
         },
     );
 
+    // Each work of literature lists on the pages of the subjects it names,
+    // including works a fetched index carries.
+    const works = worksPages(
+        [
+            ...pages.map((page) =>
+                worksNode(page.fm, { title: pageTitle(page), url: page.url, package: page.pkg }),
+            ),
+            ...foreignWorksNodes(foreign?.index),
+        ],
+        { types: new Set(Object.keys(NOTE_VOCABULARY)) },
+    );
+
     let withMap = 0;
     const outputs = capture === true ? new Map() : null;
     for (const { page, body, data } of rendered) {
         const block = related.get(page.url);
         if (block) data.related = block;
         Object.assign(data, holdings.get(page.url));
+        Object.assign(data, works.get(page.url));
         const map = maps.get(page.url);
         if (map) {
             data.map = map.name;

package/engine/stub-lint.mjs

@@ -18,6 +18,8 @@
  * a `draft` tag or a frontmatter description. Placeholder-only bodies remain
  * errors. A nonempty body below twenty-five words receives a warning when it
  * is not tagged `draft`; the author decides whether that short note is done.
+ * A `folder` note is held only to the first rule: any nonempty body passes,
+ * with or without `draft`.
  *
  * Counts and the oldest drafts remain reports. Classification and indexing
  * still derive full, draft and stub states from the existing note records;
@@ -70,6 +72,10 @@ function checkNote({ fm, body, file, raw }) {
         return findings;
     }
 
+    // A folder's body describes a pack folder rather than prose a reader is
+    // asked to finish, so any nonempty body is complete.
+    if (fm.type === "folder") return findings;
+
     const placeholders = placeholderBody(body);
     if (placeholders.length) {
         const [{ phrase }] = placeholders;

package/hugo-theme/layouts/partials/literature-works.html

@@ -0,0 +1,29 @@
+{{- /*
+  The "In song and story" card: the works of literature that name this page's
+  subject, rendered after the body and the geography and government card.
+
+  Front matter `@heroiclands/package-build` derives from every `literature`
+  lore note's `data.subjects`, and a note never authors itself:
+
+    works:  [{ title, url, form? }]  works naming this page, sorted by title
+
+  `form` is the work's `data.form` — an epic, a saga, a praise-song — printed
+  beside its name. Presence of the key is the only test: a page no work names
+  carries no `works` and renders no card. An entry with no `url` is a work
+  that publishes no page, rendered as plain text by `holdings/entry.html`.
+*/ -}}
+{{- with .Params.works -}}
+<section class="holdings literature-works" data-pagefind-ignore>
+  <div class="holdings-table">
+    <h3 class="holdings-table-label">In song and story</h3>
+    <ul class="holdings-table-grid">
+      {{- range . }}
+      <li>
+        {{- partial "holdings/entry.html" (dict "entry" . "class" "holdings-entry-name") -}}
+        {{- with .form }}<span class="holdings-entry-kind"> ({{ . }})</span>{{ end -}}
+      </li>
+      {{- end }}
+    </ul>
+  </div>
+</section>
+{{- end -}}

package/hugo-theme/layouts/partials/page-body.html

@@ -71,6 +71,7 @@
     </div>
 
     {{ partial "holdings.html" . }}
+    {{ partial "literature-works.html" . }}
     {{ partial "place-map.html" . }}
     {{ partial "related.html" . }}
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.28.0",
+    "version": "23.0.0",
     "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/sohl/default-item-art.mjs

@@ -53,17 +53,17 @@
  * build translates once and no second copy of those three rows exists.
  */
 export const DEFAULT_ITEM_ART = {
-    affiliation: "sohl/assets/icons/noun/shield.svg",
+    affiliation: "sohl/assets/icons/noun/shieldnn.svg",
     affliction: "sohl/assets/icons/other/sick.svg",
     armorgear: "sohl/assets/icons/game-icons/lorc/breastplate.svg",
-    attribute: "sohl/assets/icons/other/charm.svg",
+    attribute: "sohl/assets/icons/game-icons/lorc/charm.svg",
     concoctiongear: "sohl/assets/icons/game-icons/badges/flask.svg",
     containergear: "sohl/assets/icons/other/sack.svg",
-    miscgear: "sohl/assets/icons/other/question-mark.svg",
-    mystery: "sohl/assets/icons/other/sparkles.svg",
-    mysticalability: "sohl/assets/icons/other/hand-sparkles.svg",
+    miscgear: "sohl/assets/icons/other/questionmark.svg",
+    mystery: "sohl/assets/icons/game-icons/delapouite/sparkles.svg",
+    mysticalability: "sohl/assets/icons/other/handsparkles.svg",
     projectilegear: "sohl/assets/icons/noun/arrow.svg",
-    skill: "sohl/assets/icons/other/head-gear.svg",
+    skill: "sohl/assets/icons/other/headgear.svg",
     trauma: "sohl/assets/icons/other/injury.svg",
     weapongear: "sohl/assets/icons/other/sword.svg",
 };

package/types/engine/literature-notes.d.mts

@@ -0,0 +1,29 @@
+/**
+ * Require `data.language` to address a `skill` note whose subType is
+ * `language`.
+ *
+ * An Address that does not resolve is the reference check's to report, so
+ * this speaks only about a target that exists and is the wrong kind.
+ *
+ * @param {object} note
+ * @param {{index?: object}} [options]
+ * @returns {object[]} The findings.
+ */
+export function checkLanguageChoice(note: object, { index }?: {
+    index?: object;
+}): object[];
+/**
+ * Refuse a literature field on a lore note of any other subType.
+ *
+ * @param {object} note
+ * @returns {object[]} One error per literature key written off `literature`.
+ */
+export function checkLiteratureNote(note: object): object[];
+/** The `lore` subType whose notes are works of literature. */
+export const LITERATURE_SUBTYPE: "literature";
+/**
+ * The fields a `literature` note may state. Every one is optional.
+ *
+ * @type {ReadonlyArray<object>}
+ */
+export const LITERATURE_FIELDS: ReadonlyArray<object>;

package/types/engine/literature-works.d.mts

@@ -0,0 +1,68 @@
+/**
+ * One local page's node.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {{title: string, url?: string, package?: string}} page
+ * @returns {WorksNode|null} Null for a note with no type or shortcode.
+ */
+export function worksNode(fm: object, { title, url, package: pkg }: {
+    title: string;
+    url?: string;
+    package?: string;
+}): WorksNode | null;
+/**
+ * The works a fetched index carries, as nodes. Only a work can list itself on
+ * a page, and only a page of this package can carry the list, so a foreign
+ * entry that is not a work is never needed here.
+ *
+ * @param {Map<string, object>|undefined} foreignIndex
+ * @returns {WorksNode[]}
+ */
+export function foreignWorksNodes(foreignIndex: Map<string, object> | undefined): WorksNode[];
+/**
+ * Invert every work's subjects into the list each subject's page carries.
+ *
+ * A subject is resolved in its work's own package. A work naming one subject
+ * twice lists once; a work naming itself is not listed on its own page.
+ * Entries sort by title.
+ *
+ * @param {Iterable<WorksNode|null>} nodes - Every local page, then any foreign work.
+ * @param {object} options
+ * @param {ReadonlySet<string>} options.types - Note types an Address may name.
+ * @returns {Map<string, {works: WorkEntry[]}>} Keyed by the subject page's URL.
+ */
+export function worksPages(nodes: Iterable<WorksNode | null>, { types }: {
+    types: ReadonlySet<string>;
+}): Map<string, {
+    works: WorkEntry[];
+}>;
+/** The page front-matter key the site build writes. */
+export const WORKS_KEY: "works";
+export type WorkEntry = {
+    title: string;
+    url?: string;
+    form?: string;
+};
+export type WorksNode = {
+    /**
+     * Own Address, normalized to the `note` system.
+     */
+    key: string;
+    title: string;
+    /**
+     * Absent for a note that publishes no page.
+     */
+    url?: string | undefined;
+    /**
+     * Owning content package.
+     */
+    package?: string | undefined;
+    /**
+     * A work's `data.form`.
+     */
+    form?: string | undefined;
+    /**
+     * A work's `data.subjects`; empty for any other note.
+     */
+    subjects: unknown[];
+};