@heroiclands/package-build 22.18.0 → 22.19.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @heroiclands/package-build
 
+## 22.19.0
+
+### Minor Changes
+
+**Beings**
+
+- Beings can be described as Commoners, Entertainers, or Guildspeople, and Commoner stands alone when no other archetype fits.
+
+### Patch Changes
+
+- Books place infoboxes after each entry’s authored content, and Foundry journals place each infobox on its own page after the authored pages.
+
 ## 22.18.0
 
 ### Minor Changes

package/README.md

@@ -18,7 +18,7 @@ The generated project includes a homepage, website and book targets, npm scripts
 
 ## Documentation
 
-The documentation lives in the Markdown files in this repository. Start with [the documentation home](docs/index.md).
+The documentation lives in the Markdown files in this repository. Start with [the documentation home](docs/index.md). This toolchain does not build its own site or book. A Hugo theme dependency would form a cycle because the theme uses package-build for releases.
 
 | Topic                                             | Guide                                                        |
 | ------------------------------------------------- | ------------------------------------------------------------ |

package/docs/api.md

@@ -417,7 +417,7 @@ The infobox declarations this toolchain ships, one per system, and the single ca
 
 ### `engine.infoboxRender`
 
-Drawing a declared infobox: HTML for a Foundry Journal Page, Typst for the book. The website's boxes travel in front matter and the site theme draws them, so there is no renderer for it here.
+Drawing a declared infobox: HTML for separate Foundry pages appended after authored pages, Typst panels after each note’s authored body in the book. The website's boxes travel in front matter and the site theme draws them, so there is no renderer for it here.
 
 | Export                 | Signature                             | Returns   | Use it when                                                              |
 | ---------------------- | ------------------------------------- | --------- | ------------------------------------------------------------------------ |

package/docs/authoring/frontmatter.md

@@ -31,10 +31,12 @@ The formatter keeps a collection on one line when the full line is under 100 cha
 
 The [note-type reference](../reference/note-types.md) lists every field accepted under `data`, including the shared `id`, `pack`, `packFolder`, `harnworld`, `icon`, and `banner` fields. A type such as `being` also has its own fields, including `culture`, `homes`, and `affiliations`. A field absent from a type's vocabulary is a lint error; an unrelated field is not silently repurposed.
 
+A being's `data.archetypes` names the roles it can fill in an adventure. Choose every specific role that fits, such as `entertainer` for a performer or `guildsperson` for someone whose professional training or connections matter. Use `[commoner]` when no specific archetype fits. `commoner` cannot share the list with another value. The [archetype reference](../reference/format-details.md#actors) defines the available roles.
+
 A `sohl:` or `hm3:` block holds values for that Foundry system. Its `system:` child contains values sent to the system's DataModel. The system block can override shared routing and art where the declared field permits it. `data.pack` and `data.packFolder` are shared routes; a system-specific route belongs in that system block. The [detailed mapping reference](../reference/format-details.md#mappings-every-type-shares) and [system-block explanation](../reference/format-details.md#frontmatter-has-three-regions) cover precedence and emitted fields.
 
 One body describes the subject for both systems. A being's `{#appearance}` and `{#dossier}` sections feed SoHL Actor `system.appearance` and `system.dossier`, and HM3 Actor `system.description` and `system.biography`. An Item's `{#description}` page becomes a shared JournalEntryPage. Its resolved `@UUID[...]` pointer is stored in SoHL Item `system.docHtml` and HM3 Item `system.description`. An Item with no `{#description}` anchor uses its first page. Other H1 pages remain linkable.
 
 ## Publication and summaries
 
-A note infobox draws from shared `data`. A being profile shows its top-level `subType` as `Type: Character`, `Type: NPC`, or `Type: Creature`. A system infobox draws from the system's fields, and a mapped system with no document says “Not available.” The same authored body appears in Foundry, on the website, and in the book; presentation adapts to each medium. [Infobox details](../reference/format-details.md#the-infobox) describe field order and empty values.
+A note infobox draws from shared `data`. A being profile shows its top-level `subType` as `Type: Character`, `Type: NPC`, or `Type: Creature`. A system infobox draws from the system's fields, and a mapped system with no document says “Not available.” The same authored body appears in Foundry, on the website, and in the book; the book places boxes after the authored body, Foundry appends one page per box, and the website places boxes in its responsive side rail. [Infobox details](../reference/format-details.md#the-infobox) describe field order and empty values.

package/docs/reference/format-details.md

@@ -11,10 +11,12 @@ subType: reference
 
 Markdown generates a JournalEntry: content before the first H1 becomes its "Introduction" page, and each H1 begins another page. The document Address is `<package>-note-<note_type>-<shortcode>`.
 
-An **infobox** is prepended to the entry's first page, before the prose. It is
-not a page of its own: a page is what a Foundry UUID addresses, and a summary a
-reader has to navigate to is a summary they do not see. What the box holds, and
-where it sits in every other medium, is [the infobox](#the-infobox) below.
+Each emitted infobox becomes a separate page at the end of the JournalEntry,
+after every authored page. The page names are **Properties Infobox**,
+**SoHL Infobox**, and **HM3 Infobox**, in that order where emitted. Generated
+page ids derive from the entry and box identity, separately from authored
+heading names and anchors. An authored heading may share an infobox page name.
+What the boxes hold is [the infobox](#the-infobox) below.
 
 **There are two kinds of infobox.**
 
@@ -62,16 +64,13 @@ For web pages, the full Markdown body renders as HTML with its infoboxes.
 
 ### The infobox
 
-**The infobox is generated content at a known position — prepended, before the
-prose.** It is not a floating sidebar and it is not defined in a rendering
-template. The toolchain settles what each box holds; each medium lays that out
-its own way.
+**The toolchain settles what each box holds; each medium places it.**
 
-| medium  | placement                                              | collapsing                |
-| ------- | ------------------------------------------------------ | ------------------------- |
-| book    | flows in the column measure, breaking between sections | none, and none needed     |
-| website | side rail on wide screens, inline on narrow            | `<details>`, default open |
-| Foundry | inlined, the page being narrow                         | `<details>`, default open |
+| medium  | placement                                                                                                     | collapsing                |
+| ------- | ------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| book    | after the note's authored body, before the next entry; flows in the column measure, breaking between sections | none                      |
+| website | side rail on wide screens, inline on narrow screens                                                           | `<details>`, default open |
+| Foundry | one page per emitted box, after all authored pages                                                            | `<details>`, default open |
 
 Two columns are print-only. A scrolling page has no fixed viewport, so columns
 make a reader travel down and back up, and a narrow screen collapses to one
@@ -79,8 +78,8 @@ column regardless.
 
 **Six rules hold in every medium.**
 
-1. **It is content in document order**, prepended before the prose. An image
-   authored before it appears before it.
+1. **Placement belongs to the medium**, as described above. Authored images
+   remain in the body in their authored order.
 2. **It contains no image.** A picture is authored in the text with its own
    directive, and its position governs.
 3. **A section is the unit that flows.** Sections are whole and unbreakable and
@@ -442,16 +441,16 @@ surface:
 > **Draft.** This entry is unfinished. What it states may change, and nothing in
 > it is settled.
 
-It leads the entry — above the infobox and above the prose — because a reader
+It leads the entry, before the authored content, because a reader
 deciding whether to rely on an entry has to be told before they read it. Where
 it lands:
 
-| Surface      | What carries it                                                      |
-| ------------ | -------------------------------------------------------------------- |
-| JournalEntry | a `blockquote.sohl-draft-notice` at the head of the first page       |
-| Actor        | the dossier the sheet draws — SoHL's `dossier`, HM3's `biography`    |
-| The book     | a drawn mark and a left rule between the entry's plate and its panel |
-| The website  | the theme's own notice, above the infobox rail and the prose         |
+| Surface      | What carries it                                                              |
+| ------------ | ---------------------------------------------------------------------------- |
+| JournalEntry | a `blockquote.sohl-draft-notice` at the head of the first page               |
+| Actor        | the dossier the sheet draws — SoHL's `dossier`, HM3's `biography`            |
+| The book     | a drawn mark and a left rule between the entry's plate and its authored body |
+| The website  | the theme's own notice, above the infobox rail and the prose                 |
 
 **An Actor carries it once.** A being's prose reaches two fields, and a document
 saying the same thing twice teaches a reader to skip it — a printed sheet draws
@@ -2445,8 +2444,13 @@ For JournalEntries, the following rules apply:
 - mariner: Handles boats and blue water.
 - artisan: Builds, repairs, and appraises craft work.
 - trader: Moves goods, values them, and knows markets.
+- commoner: Fits no more specific archetype; handles ordinary work and daily life.
+- entertainer: Performs for an audience through acting, music, comedy, or similar arts.
+- guildsperson: Has professional training, standing, or connections that open doors.
 
 Note that archetypes are descriptive, not proscriptive, and a character may be described by multiple archetypes at once.
+`commoner` stands alone: a being with another fitting archetype does not also carry `commoner`.
+Guild membership alone does not require `guildsperson`; the being's training, standing, or connections must matter to the role.
 
 #### Items
 

package/engine/frontmatter-lint.mjs

@@ -1173,6 +1173,19 @@ export function lintNote(
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
+    if (
+        type === "being" &&
+        Array.isArray(fm.data?.archetypes) &&
+        fm.data.archetypes.includes("commoner") &&
+        fm.data.archetypes.length > 1
+    ) {
+        findings.push({
+            file: note.file,
+            ...at("archetypes", "commoner"),
+            severity: "error",
+            message: "`data.archetypes` may contain `commoner` only by itself",
+        });
+    }
     /**
      * The in-block keys this note's own type claims for something other than
      * the note-level field of that name, which every note-level check below

package/engine/infobox.mjs

@@ -51,9 +51,9 @@
  *
  * ## Six rules that hold in every medium
  *
- * 1. **The infobox is generated content in document order** — prepended,
- *    before the prose. Not a floating sidebar. An image authored before it
- *    appears before it.
+ * 1. **Placement belongs to the medium.** The book puts boxes after the
+ *    authored body, Foundry appends one page per box, and the website uses
+ *    a side rail on wide screens and inline boxes on narrow screens.
  * 2. **It contains no image.** A picture is authored in the text with its own
  *    directive, and its position governs. {@link NOTE_FIELD_PRESENTATION}
  *    withholds the art slots and `overlay` for that reason and no other.

package/engine/journals.mjs

@@ -335,16 +335,13 @@ export function buildPages(rawPages, entryId, noteName, captions) {
  *   entry: a module may ship the same content for two systems, and each pack's
  *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
- * @param {string} [params.infobox] - The note's infobox, already rendered to
- *   HTML. Prepended to the entry's first page, which is where the format puts
- *   it: the box is generated content in document order, before the prose, and
- *   a Foundry page is narrow enough that inlining it is the only arrangement
- *   that reads. It is **not** a page of its own — a page is what a UUID
- *   addresses, and a summary a reader has to navigate to is a summary they do
- *   not see.
+ * @param {Array<{id: string, name: string, html: string}>} [params.infoboxes] -
+ *   Emitted boxes, each rendered to HTML. Each becomes a separate page after
+ *   the authored pages. Its identity uses the box id in a generated-page
+ *   namespace, independent of authored headings and anchors.
  * @param {string} [params.notice] - A statement about the entry rather than
  *   about its subject, already rendered to HTML — see {@link
- *   module:engine/draft-notice}. It leads the first page, ahead of the infobox,
+ *   module:engine/draft-notice}. It leads the first authored page,
  *   because a reader deciding whether to rely on the entry has to be told
  *   before they read it rather than after.
  * @returns {object} The JournalEntry document, keyed for the pack.
@@ -357,13 +354,21 @@ export function buildJournalEntry({
     folder = null,
     flags,
     stats = defaultStats(),
-    infobox = "",
+    infoboxes = [],
     notice = "",
 }) {
     const rawPages = splitPages(markdown, leadName);
     const pages = buildPages(rawPages, id, name, scanCaptions(markdown).captions);
-    if (infobox.trim() && pages.length) {
-        pages[0].text.content = `${infobox}\n${pages[0].text.content}`;
+    for (const box of infoboxes) {
+        const pageId = makeId("journal-infobox-page", `${id}:${box.id}`);
+        pages.push({
+            _id: pageId,
+            name: box.name,
+            type: "text",
+            title: { show: true, level: 1 },
+            text: { format: 1, content: box.html },
+            _key: `!journal.pages!${id}.${pageId}`,
+        });
     }
     if (notice.trim() && pages.length) {
         pages[0].text.content = `${notice}\n${pages[0].text.content}`;
@@ -522,7 +527,15 @@ export class Journals extends BasePackCompiler {
             id,
             name,
             markdown,
-            infobox: infoboxesToHtml(boxes, { link: linkToUuid }),
+            infoboxes: boxes.map((box) => ({
+                id: box.id,
+                name: `${
+                    box.id === "note" ? "Properties"
+                    : box.id === "sohl" ? "SoHL"
+                    : "HM3"
+                } Infobox`,
+                html: infoboxesToHtml([box], { link: linkToUuid }),
+            })),
             // Whether the entry is settled, asked of the tag through the one
             // reader of it. This sits here rather than in `buildJournalEntry`
             // for the reason `skipNote` runs first: a note with no prose

package/engine/pdf-build.mjs

@@ -639,9 +639,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             anchorPrefix,
             captions: numberedCaptions,
         });
-        // The infobox is generated content in document order — prepended,
-        // before the prose. An image the note authored ahead of it still comes
-        // first, because the image lives in the body and the body follows.
+        // Infoboxes follow the authored body within this note's entry.
         const boxes = noteInfoboxes(page.fm, {
             resolve: (ref, hint) => resolveInfoboxRef(gates.index, ref, hint),
             router: routerFor(resolved),
@@ -651,10 +649,9 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
             link: (value) => linkToTypst(value, plan.links, labelFor),
         });
         // Whether the entry is settled comes before anything it says: the
-        // notice leads the leaf, ahead of the panel, which is the position it
-        // holds on every other surface.
+        // notice leads the leaf, before the authored body.
         const notice = isDraftNote(page.fm) ? draftNoticeTypst() : "";
-        const parts = [notice, panel, prose].filter((part) => part);
+        const parts = [notice, prose, panel].filter((part) => part);
         return parts.join("\n\n");
     };
 

package/engine/site-build.mjs

@@ -984,7 +984,6 @@ export function renderPages(pages, options) {
  */
 const SITE_PASSES = Object.freeze({
     sohlKb: () => require("../sohl/kb-passes.mjs").sohlKbPass,
-    packageDocs: () => require("./documentation-links.mjs").documentationLinksPass,
 });
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.18.0",
+    "version": "22.19.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",
@@ -174,7 +174,6 @@
     },
     "devDependencies": {
         "@changesets/cli": "^3.0.0",
-        "@heroiclands/hugo-theme": "^0.9.0",
         "@types/node": "^26.2.0",
         "npm-run-all": "^4.1.5",
         "vitest": "^5.0.0"
@@ -198,16 +197,7 @@
         "changeset": "changeset",
         "changeset:version": "changeset version && node bin/package-build.mjs changelog group && npm install --package-lock-only",
         "prepare": "git config core.hooksPath .githooks || true",
-        "build:deps": "node bin/package-build.mjs deps fetch",
-        "build:content-index": "node bin/package-build.mjs content-index",
-        "build:site-content": "node bin/package-build.mjs site",
-        "build:site-html": "hugo --source build/hugo --minify --gc --cleanDestinationDir",
-        "build:site-root": "node bin/package-build.mjs site-root",
-        "build:site": "run-s build:deps build:content-index build:site-content build:site-html build:site-root",
-        "build:book": "run-s build:deps build:content-index build:book-content",
-        "build:book-content": "node bin/package-build.mjs pdf",
-        "serve:site": "run-s build:deps build:content-index build:site-content serve:site-html",
-        "serve:site-html": "hugo server --source build/hugo"
+        "build:deps": "node bin/package-build.mjs deps fetch"
     },
     "engines": {
         "node": ">=24.0.0"

package/types/engine/journals.d.mts

@@ -139,21 +139,18 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   entry: a module may ship the same content for two systems, and each pack's
  *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
- * @param {string} [params.infobox] - The note's infobox, already rendered to
- *   HTML. Prepended to the entry's first page, which is where the format puts
- *   it: the box is generated content in document order, before the prose, and
- *   a Foundry page is narrow enough that inlining it is the only arrangement
- *   that reads. It is **not** a page of its own — a page is what a UUID
- *   addresses, and a summary a reader has to navigate to is a summary they do
- *   not see.
+ * @param {Array<{id: string, name: string, html: string}>} [params.infoboxes] -
+ *   Emitted boxes, each rendered to HTML. Each becomes a separate page after
+ *   the authored pages. Its identity uses the box id in a generated-page
+ *   namespace, independent of authored headings and anchors.
  * @param {string} [params.notice] - A statement about the entry rather than
  *   about its subject, already rendered to HTML — see {@link
- *   module:engine/draft-notice}. It leads the first page, ahead of the infobox,
+ *   module:engine/draft-notice}. It leads the first authored page,
  *   because a reader deciding whether to rely on the entry has to be told
  *   before they read it rather than after.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infobox, notice, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infoboxes, notice, }: {
     id: string;
     name: string;
     markdown: string;
@@ -161,7 +158,11 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, flags,
     folder?: string | null | undefined;
     flags?: object | undefined;
     stats?: object | undefined;
-    infobox?: string | undefined;
+    infoboxes?: {
+        id: string;
+        name: string;
+        html: string;
+    }[] | undefined;
     notice?: string | undefined;
 }): object;
 /**

package/engine/documentation-links.mjs

@@ -1,31 +0,0 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
-
-import fs from "node:fs";
-import path from "node:path";
-
-import { parseMarkdownFile } from "./helpers.mjs";
-
-const LOCAL_MARKDOWN_LINK = /\[([^\]\n]+)\]\(([^\s)]+\.md(?:#[^\s)]*)?)\)/g;
-
-/** Keep repository-relative documentation links usable on addressed pages. */
-export function documentationLinksPass({ config, book = false }) {
-    const root = config.paths.content;
-    const cache = new Map();
-    return {
-        beforeLinks(text, page) {
-            return text.replace(LOCAL_MARKDOWN_LINK, (whole, label, target) => {
-                const [fileName, fragment] = target.split("#", 2);
-                const file = path.resolve(path.dirname(page.file), fileName);
-                if (!file.startsWith(`${root}${path.sep}`) || !fs.existsSync(file)) return whole;
-                let address = cache.get(file);
-                if (!address) {
-                    const { frontmatter } = parseMarkdownFile(file);
-                    if (!frontmatter?.type || !frontmatter?.shortcode) return whole;
-                    address = `/${config.contentPackage}/${frontmatter.type}-${frontmatter.shortcode}/`;
-                    cache.set(file, address);
-                }
-                return `[${label}](${address}${fragment && !book ? `#${fragment}` : ""})`;
-            });
-        },
-    };
-}

package/types/engine/documentation-links.d.mts

@@ -1,7 +0,0 @@
-/** Keep repository-relative documentation links usable on addressed pages. */
-export function documentationLinksPass({ config, book }: {
-    config: any;
-    book?: boolean | undefined;
-}): {
-    beforeLinks(text: any, page: any): any;
-};