@heroiclands/package-build 23.1.1 → 23.2.0

package/content-config.mjs

@@ -197,36 +197,6 @@ export const PACK_DOCUMENT_TYPES = /** @type {const} */ ([
     "Scene",
 ]);
 
-/**
- * Address-scheme keys a configuration may no longer declare.
- *
- * A retired key has exactly two possible fates, and only one of them is honest
- * — the same reasoning `engine/retired-fields.mjs` applies to a retired
- * frontmatter field. Left honoured, it keeps doing whatever it did, which is
- * why it was retired. Left *ignored*, it reads to its author as though it still
- * works: the configuration says one thing and the build does another, and
- * nothing says so. This module has no third option, because it has no warning
- * channel — every finding goes through `fail()`, which throws. So a retired
- * key is **refused**, at the line it was written on, with a message that says
- * the mechanism is gone rather than naming a value to correct.
- *
- * **`landing` is one such key.** It named which note addressed a whole section
- * rather than a page within one — a *landing page*, which therefore had no slug
- * of its own. There are no sections to address: a section is a Hugo content
- * directory the note format does not carry, a page's address names no
- * directory, and so no note lands anything.
- *
- * @type {Readonly<Record<string, string>>}
- */
-export const RETIRED_ADDRESS_KEYS = Object.freeze({
-    landing:
-        "is a retired option — delete it. It named which note addressed a " +
-        "whole section rather than a page within one, and there are no " +
-        "sections to address: a section is a Hugo content directory the note " +
-        "format does not carry, so no note lands one and every page is " +
-        "addressed `<type>-<shortcode>`. Nothing replaces it",
-});
-
 /**
  * A repository's address scheme, with the defaults an unconfigured one gets.
  *
@@ -237,9 +207,7 @@ export const RETIRED_ADDRESS_KEYS = Object.freeze({
  * knowledge, held in `PACKAGE_BASE` (`engine/content-address.mjs`) and prefixed at
  * resolve time, so it is never recorded here.
  *
- * It is the whole scheme: `landing`, the key that named which note addressed a
- * whole section, is retired with the sections themselves — see
- * {@link RETIRED_ADDRESS_KEYS}.
+ * It is the whole scheme.
  */
 export const DEFAULT_ADDRESS_SCHEME = Object.freeze({
     prefix: "",
@@ -581,6 +549,18 @@ export function publishesContentPages(config) {
  * @property {Record<string, ItemBuilderEntry>} builders  The registry itself.
  */
 
+/**
+ * One person in the top-level `authors` list.
+ *
+ * @typedef {object} AuthorSpec
+ * @property {string} name       As printed.
+ * @property {string} [email]
+ * @property {string} [url]
+ * @property {string} [discord]  A Discord handle, as Foundry's author schema
+ *                               carries one.
+ * @property {string} [role]     One of {@link AUTHOR_ROLES}.
+ */
+
 /**
  * The configuration a consumer writes.
  *
@@ -601,9 +581,10 @@ export function publishesContentPages(config) {
  *                                          the site build's `baseURL`. Checked
  *                                          by `checkHomepage` in
  *                                          `config.mjs`.
- * @property {string|{name: string, email?: string, url?: string}} [author]
- *                                          `package.json`'s own `author`, in
- *                                          either of npm's forms.
+ * @property {AuthorSpec[]} [authors]       The people who made the
+ *                                          package. The Foundry manifest's
+ *                                          `authors` and the site's byline
+ *                                          are generated from it.
  * @property {PackageKind} packageKind      Whether the package is a system, a
  *                                          module, or documentation — the kind
  *                                          that publishes a site and a book
@@ -669,10 +650,13 @@ export function publishesContentPages(config) {
  * @property {string|null} homepage    `package.json`'s own `homepage`,
  *                                     checked by `checkHomepage` in
  *                                     `config.mjs`.
+ * @property {readonly Readonly<AuthorSpec>[]} authors  The people who made
+ *                                     the package, in the order declared; `[]`
+ *                                     when none are.
  * @property {Readonly<{name: string, email?: string, url?: string}>|null} author
- *                                     `package.json`'s own `author`, normalised
- *                                     from either of npm's forms; `null` when
- *                                     the package declares none.
+ *                                     Derived: the first of `authors`, in npm's
+ *                                     `author` shape — the site's byline.
+ *                                     `null` when no author is declared.
  * @property {PackageKind} packageKind
  * @property {string|null} assetRoot   Derived, and **conditional**: the served
  *                                     Foundry asset root,
@@ -744,7 +728,7 @@ const CONFIG_KEYS = [
     "contentPackage",
     "foundryPackage",
     "homepage",
-    "author",
+    "authors",
     "packageKind",
     "stats",
     "itemBuilders",
@@ -783,7 +767,42 @@ const SITE_KEYS = [
 ];
 const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
 const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
-const PDF_KEYS = ["title", "subtitle", "document", "out", "front", "fonts", "iconFonts", "binary"];
+const PDF_KEYS = [
+    "books",
+    "out",
+    "fonts",
+    "iconFonts",
+    "binary",
+    "unprinted",
+    "coverage",
+    "indexSeeAlso",
+    "copyright",
+    "license",
+];
+const PDF_BOOK_KEYS = [
+    "id",
+    "title",
+    "subtitle",
+    "coverImage",
+    "front",
+    "out",
+    "contents",
+    "document",
+];
+/**
+ * How a printable note no book selects is reported: `pdf.coverage`.
+ *
+ * @type {readonly string[]}
+ */
+const PDF_COVERAGE = Object.freeze(["warning", "error", "off"]);
+/**
+ * What a book `id` may be. It is written on the command line as `--book <id>`
+ * and is the tail of the book's default file stem, so it takes the charset a
+ * file name and an address segment share.
+ */
+const PDF_BOOK_ID = /^[a-z0-9][a-z0-9-]*$/;
+/** What a book's file stem may be: one path segment, no directory. */
+const PDF_BOOK_STEM = /^[\w.-]+$/;
 const PDF_FONT_KEYS = ["serif", "sans", "mono", "path"];
 const EMPTY_PDF_FONTS = Object.freeze({ serif: "", sans: "", mono: "", path: "" });
 const DOC_PAGE_KEYS = ["title", "out", "preamble", "frontmatter"];
@@ -808,7 +827,28 @@ export const RELATIONSHIP_KEYS = [
     "contentIndex",
     "assetReplacement",
 ];
-const AUTHOR_KEYS = ["name", "email", "url"];
+const AUTHOR_KEYS = ["name", "email", "url", "discord", "role"];
+/**
+ * The closed list a person's `role` in `authors` is drawn from.
+ *
+ * One role per entry: a person with two roles is listed twice. Printed in
+ * title case after the name on a book's title page; the Foundry manifest,
+ * whose author schema has no role, never receives it.
+ *
+ * @type {readonly string[]}
+ */
+export const AUTHOR_ROLES = Object.freeze([
+    "author",
+    "designer",
+    "developer",
+    "editor",
+    "proofreader",
+    "artist",
+    "cartographer",
+    "layout",
+    "playtester",
+    "translator",
+]);
 const ITEM_BUILDER_KEYS = ["system", "img", "fields"];
 const ITEM_REGISTRY_KEYS = ["system", "builders"];
 const PACK_KEYS = [
@@ -1029,52 +1069,60 @@ function optionalString(value, field) {
 }
 
 /**
- * npm's `author` field, in either of its two forms.
- *
- * `package.json` accepts a single string — `"Name <email> (url)"`, with the
- * email and the URL both optional — or an object carrying the same three
- * parts. Both normalise to one shape, so the site build reads one field
- * instead of branching on which form a repository happened to write.
- *
- * @type {RegExp}
- */
-const AUTHOR_STRING = /^([^<(]*?)\s*(?:<([^>]*)>)?\s*(?:\(([^)]*)\))?\s*$/;
+ * The people who made the package: the top-level `authors` list.
+ *
+ * The one place a package names its people. The Foundry manifest's `authors`
+ * is generated from it with `role` dropped, because Foundry's author schema
+ * has none; the byline the site build reads is its first entry's name, email
+ * and URL. Each entry is `{name, email?, url?, discord?, role?}`, and `role`
+ * is drawn from {@link AUTHOR_ROLES}.
+ *
+ * @param {unknown} value - The declared `authors`, or `undefined`.
+ * @returns {readonly Readonly<AuthorSpec>[]} The entries, frozen; `[]` when
+ *   none are declared.
+ */
+function normalizeAuthors(value) {
+    if (value === undefined) return Object.freeze([]);
+    if (!Array.isArray(value)) {
+        fail("authors", "must be a list of people, each a mapping with at least a `name`");
+    }
+    return Object.freeze(
+        value.map((entry, i) => {
+            const where = `authors[${i}]`;
+            if (!isPlainObject(entry)) fail(where, "must be a mapping with at least a `name`");
+            const person = /** @type {Record<string, unknown>} */ (entry);
+            rejectUnknownKeys(person, AUTHOR_KEYS, `${where}.`);
+            const out = { name: requireNonEmptyString(person.name, `${where}.name`) };
+            for (const key of ["email", "url", "discord"]) {
+                if (person[key] !== undefined) {
+                    out[key] = requireNonEmptyString(person[key], `${where}.${key}`);
+                }
+            }
+            if (person.role !== undefined) {
+                if (typeof person.role !== "string" || !AUTHOR_ROLES.includes(person.role)) {
+                    fail(`${where}.role`, `must be one of: ${AUTHOR_ROLES.join(", ")}`);
+                }
+                out.role = person.role;
+            }
+            return Object.freeze(out);
+        }),
+    );
+}
 
 /**
- * @param {unknown} value - The declared `author`, or `undefined`.
- * @returns {Readonly<{name: string, email?: string, url?: string}>|null}
- *   `null` when the package declares none.
+ * The package's byline: the first of `authors`, as npm's `author` shape.
+ *
+ * @param {readonly Readonly<AuthorSpec>[]} authors - From {@link normalizeAuthors}.
+ * @returns {Readonly<{name: string, email?: string, url?: string}>|null} `null`
+ *   when no author is declared.
  */
-function normalizeAuthor(value) {
-    if (value === undefined) return null;
-    if (typeof value === "string") {
-        const match = AUTHOR_STRING.exec(value.trim());
-        const name = match?.[1]?.trim();
-        if (!match || !name) {
-            fail(
-                "author",
-                'must be `"Name"`, `"Name <email>"`, `"Name (url)"` or ' +
-                    '`"Name <email> (url)"` — npm\'s own `author` forms',
-            );
-        }
-        return Object.freeze({
-            name: /** @type {string} */ (name),
-            ...(match[2] ? { email: match[2] } : {}),
-            ...(match[3] ? { url: match[3] } : {}),
-        });
-    }
-    if (!isPlainObject(value)) {
-        fail("author", "must be a string or an object with `name`, `email` and `url`");
-    }
-    const author = /** @type {Record<string, unknown>} */ (value);
-    rejectUnknownKeys(author, AUTHOR_KEYS, "author.");
-    const name = requireNonEmptyString(author.name, "author.name");
+function bylineOf(authors) {
+    const [first] = authors;
+    if (!first) return null;
     return Object.freeze({
-        name,
-        ...(author.email !== undefined ?
-            { email: optionalString(author.email, "author.email") }
-        :   {}),
-        ...(author.url !== undefined ? { url: optionalString(author.url, "author.url") } : {}),
+        name: first.name,
+        ...(first.email !== undefined ? { email: first.email } : {}),
+        ...(first.url !== undefined ? { url: first.url } : {}),
     });
 }
 
@@ -1088,19 +1136,6 @@ function normalizeAuthor(value) {
 function normalizePack(value, where, nested = false) {
     if (!isPlainObject(value)) fail(where, "must be an object");
     const pack = /** @type {Record<string, unknown>} */ (value);
-    // Retired with the YAML it named. Refused explicitly rather than
-    // left to the unknown-key check, because the useful thing to say is not
-    // "no such key" but where the folders went: they are notes, and a pack
-    // materialises the ones its documents reference.
-    if (pack.folders !== undefined) {
-        fail(
-            `${where}.folders`,
-            "is retired — delete it. A folder is a note (`type: folder`) now, " +
-                "and a pack materialises the folders its documents reference " +
-                "through `packFolder`, so there is no per-pack hierarchy file " +
-                "to name",
-        );
-    }
     rejectUnknownKeys(pack, PACK_KEYS, `${where}.`);
 
     const name = requireNonEmptyString(pack.name, `${where}.name`);
@@ -1609,7 +1644,7 @@ export const DERIVED_HUGO_KEYS = Object.freeze({
         "the toolchain, which renders a site as its homepage and its pages: no " +
         "output format is declared, because every listing kind is disabled",
     "params.description": "`site.description`",
-    "params.author": "package.json `author`",
+    "params.author": "the first entry of `authors`",
     "params.cdnBaseURL": "`site.assets`",
     "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
     "params.notfound": "`site.notfound`",
@@ -1695,38 +1730,6 @@ function normalizeSiteHugo(value) {
     return Object.freeze(structuredClone(input));
 }
 
-/**
- * The keys that asked the site build to write an index between the homepage
- * and the pages, each refused with the one message.
- *
- * A site is its homepage and its pages. Each of these keys asks for a
- * generated listing between them — `sections` (with `listType` and
- * `listSubType` inside an entry) a type-wide alphabetical one per entry,
- * `backfillSections` one for every other directory under the mount, `landing`
- * the mount's own, `list` how such a listing renders. None of those is a page
- * anyone chose the contents of, and every one of them is authored instead: a
- * `doc` note, addressed by its shortcode, carrying a content table over the
- * notes it introduces, with the columns it chooses.
- *
- * Refused rather than ignored, for the reason {@link RETIRED_ADDRESS_KEYS}
- * gives: a key left ignored reads to its author as though it still works.
- *
- * @type {readonly string[]}
- */
-const SITE_INDEX_KEYS = Object.freeze(["sections", "landing", "backfillSections", "list"]);
-
-/**
- * The message every key in {@link SITE_INDEX_KEYS} is refused with.
- *
- * @type {string}
- */
-const SITE_INDEX_MESSAGE =
-    "is retired — a site is its homepage and its pages, and any index between " +
-    "them is a `doc` note: write one with `type: doc`, a `shortcode` and " +
-    "`pack: none`, carrying a content table over the notes it lists, and link " +
-    "it from the homepage. Nothing is generated between the homepage and the " +
-    "pages, so delete the key";
-
 /**
  * The `site` section — how this repository frames the website it publishes.
  *
@@ -1734,7 +1737,7 @@ const SITE_INDEX_MESSAGE =
  * repository's own body rewrites, and the residue of the generated Hugo
  * configuration that is genuinely this repository's own. Where the Hugo tree
  * is written is not a choice: `package-build site` writes it under
- * `build/hugo/`, and a `site.out` is refused by name. How a page gets its
+ * `build/hugo/`. How a page gets its
  * **address** is deliberately not here either — that is `publish.address`,
  * shared with the link manifest so the two cannot disagree about where a
  * page is.
@@ -1748,12 +1751,8 @@ const SITE_INDEX_MESSAGE =
  * **What the site publishes is the homepage and the content tree, and nothing
  * beside them.** A page of documentation is a note — `type: doc`, addressed
  * by its shortcode, compiling into no document where it says `pack: none` —
- * so there is no second mechanism for mounting a directory of markdown, and a
- * configuration that names one (`site.trees`, and the `site.readmeSections`
- * that titled such a tree's landing) is refused with a message saying where
- * the page goes instead. An index between the homepage and the pages is a
- * `doc` note too, so the keys that asked the build to generate one
- * ({@link SITE_INDEX_KEYS}) are refused the same way.
+ * so there is no second mechanism for mounting a directory of markdown. An
+ * index between the homepage and the pages is a `doc` note too.
  *
  * @param {unknown} value - The `site` block, or `undefined`.
  * @returns {Readonly<object>} It, frozen, with every default filled.
@@ -1775,35 +1774,6 @@ function normalizeSite(value) {
     if (value === undefined) return empty;
     if (!isPlainObject(value)) fail("site", "must be a mapping");
     const input = /** @type {Record<string, unknown>} */ (value);
-    // Refused by name, ahead of the vocabulary check: the useful thing to say
-    // is not "no such key" but that the location is fixed.
-    if (input.out !== undefined) {
-        fail(
-            "site.out",
-            "is retired — the site build writes its content mount at " +
-                "`build/hugo/content`, beside the generated `hugo.toml`, and " +
-                "the location is not configurable. Remove the key",
-        );
-    }
-    // Refused by name too, and ahead of the vocabulary check for the same
-    // reason: a page is a note in the content tree, and the useful thing to
-    // say is where it goes rather than that the key is unknown.
-    for (const key of ["trees", "readmeSections"]) {
-        if (input[key] === undefined) continue;
-        fail(
-            `site.${key}`,
-            "is retired — a page is a note in the content tree. Give each page " +
-                "`type: doc`, a `shortcode` and `pack: none`, file it under " +
-                "`assets/content/`, and link it from the homepage or from a " +
-                "`doc` note that indexes it",
-        );
-    }
-    // And by name, for the same reason: an index between the homepage and
-    // the pages is a `doc` note, and the useful thing to say is that.
-    for (const key of SITE_INDEX_KEYS) {
-        if (input[key] === undefined) continue;
-        fail(`site.${key}`, SITE_INDEX_MESSAGE);
-    }
     rejectUnknownKeys(input, SITE_KEYS, "site.");
 
     let packages = [];
@@ -1833,46 +1803,65 @@ function normalizeSite(value) {
 }
 
 /**
- * The `pdf` section — the book the content tree is published as.
+ * One declared book, resolved.
  *
- * A third surface beside the packs and the website, and the one that is a
- * **selection** rather than a rendering of everything: `document:` names the
- * tree that says which notes the volume carries and in what order, because a
- * book is an editorial act where a site is an index. That file is the
- * consumer's, parsed by {@link module:engine/pdf-toc.parseDocumentTree}, and
- * nothing about its shape is validated here — this block says only where it is.
+ * @typedef {object} ResolvedPdfBook
+ * @property {string} id          Its name on the command line, `--book <id>`.
+ * @property {string} title
+ * @property {string} subtitle    `""` when none is declared.
+ * @property {string} coverImage  Absolute; `""` when none is declared.
+ *                                Whether the file exists is checked when the
+ *                                book is built, not here.
+ * @property {readonly string[]} front  Absolute paths of the front matter.
+ * @property {string} out         The file stem; the version is appended.
+ * @property {readonly object[]|null} contents  The tree written inline, or
+ *                                `null` when `document` names a file.
+ * @property {string} document    Absolute path of the tree's file, or `""`
+ *                                when the tree is written inline.
+ */
+
+/**
+ * The `pdf` section — the books the content tree is published as.
  *
- * **Nothing here is an address or a brand.** The title, the subtitle, the front
- * matter and the faces are every one of them the publishing repository's to
- * choose, which is the whole reason they are configuration: the engine that
- * sets the book must be able to set somebody else's book.
+ * A third surface beside the packs and the website, and the one that is a
+ * **selection** rather than a rendering of everything: each book's tree says
+ * which notes the volume carries and in what order, because a book is an
+ * editorial act where a site is an index. A tree is written inline as
+ * `contents:` or kept in the file `document:` names, and is parsed by
+ * {@link module:engine/pdf-toc.parseDocumentTree} when the book is built;
+ * nothing about its shape is validated here.
+ *
+ * `books` is the one required key. The rest of the block — faces, icon fonts,
+ * the compiler, the output directory, what no book prints, how an unprinted
+ * note is reported, and the copyright and licence statements — is shared by
+ * every book. Each book's `out` is a file stem (default
+ * `<contentPackage>-<id>`), and two books resolving to one stem is refused,
+ * since the second would overwrite the first.
+ *
+ * Paths resolve against `rootDir` here; whether `coverImage`, `document` and
+ * each `front` file exist is checked when a book is built, so a command that
+ * builds no book never fails for a missing cover.
+ *
+ * **Nothing here is an address or a brand.** The titles, the front matter and
+ * the faces are every one of them the publishing repository's to choose, which
+ * is the whole reason they are configuration: the engine that sets the book
+ * must be able to set somebody else's book.
  *
  * A PDF is built when the authored tree contains content pages and the `pdf`
- * block names a document tree. See {@link publishesContentPages}.
+ * block is present. See {@link publishesContentPages}.
  *
  * @param {unknown} value - The `pdf` block, or `undefined`.
  * @param {string} rootDir - The repository root configured paths resolve against.
+ * @param {string} contentPackage - The package name a default stem starts with.
  * @returns {Readonly<object>|null} It, frozen; `null` when the block is absent.
  */
-function normalizePdf(value, rootDir) {
+function normalizePdf(value, rootDir, contentPackage) {
     if (value === undefined) return null;
     if (!isPlainObject(value)) fail("pdf", "must be a mapping");
     const input = /** @type {Record<string, unknown>} */ (value);
     rejectUnknownKeys(input, PDF_KEYS, "pdf.");
 
-    // Both required, and required together: a document with no tree has nothing
-    // to print, and a tree with no title produces a file whose name and cover
-    // say nothing about what a reader downloaded.
-    const title = requireNonEmptyString(input.title, "pdf.title");
-    const document = requireNonEmptyString(input.document, "pdf.document");
-
-    const front = [];
-    if (input.front !== undefined) {
-        if (!Array.isArray(input.front)) fail("pdf.front", "must be a list of markdown files");
-        input.front.forEach((entry, i) => {
-            front.push(requireNonEmptyString(entry, `pdf.front[${i}]`));
-        });
-    }
+    const books = normalizePdfBooks(input.books, rootDir, contentPackage);
 
     let fonts = EMPTY_PDF_FONTS;
     if (input.fonts !== undefined) {
@@ -1919,15 +1908,21 @@ function normalizePdf(value, rootDir) {
         }
     }
 
+    const coverage = input.coverage === undefined ? "warning" : input.coverage;
+    if (typeof coverage !== "string" || !PDF_COVERAGE.includes(coverage)) {
+        fail("pdf.coverage", `must be one of: ${PDF_COVERAGE.join(", ")}`);
+    }
+    const copyright =
+        input.copyright === undefined ?
+            ""
+        :   requireNonEmptyString(input.copyright, "pdf.copyright");
+    if (/[\r\n]/.test(copyright.trim())) {
+        fail("pdf.copyright", "must be one line — the licence statement is the one that runs on");
+    }
+
     return Object.freeze({
-        title,
-        subtitle:
-            input.subtitle === undefined ?
-                ""
-            :   requireNonEmptyString(input.subtitle, "pdf.subtitle"),
-        document: path.resolve(rootDir, document),
+        books,
         out: input.out === undefined ? "" : requireNonEmptyString(input.out, "pdf.out"),
-        front: Object.freeze(front.map((f) => path.resolve(rootDir, f))),
         fonts,
         iconFonts: Object.freeze(iconFonts),
         // Where the Typst binary is, when it is not simply `typst` on PATH.
@@ -1935,9 +1930,142 @@ function normalizePdf(value, rootDir) {
         // platform-specific binary in the dependency tree of three repositories
         // that mostly do not build books.
         binary: input.binary === undefined ? "" : requireNonEmptyString(input.binary, "pdf.binary"),
+        // A `WHERE` clause over `notes` naming what belongs in no book.
+        unprinted:
+            input.unprinted === undefined ?
+                ""
+            :   requireNonEmptyString(input.unprinted, "pdf.unprinted"),
+        coverage,
+        // Whether an index names a note another book prints, as
+        // `Name: Book title, p. N`.
+        indexSeeAlso: optionalBoolean(input.indexSeeAlso, "pdf.indexSeeAlso", false),
+        copyright: copyright.trim(),
+        license:
+            input.license === undefined ?
+                ""
+            :   requireNonEmptyString(input.license, "pdf.license").trim(),
     });
 }
 
+/**
+ * The `pdf.books` list, each entry resolved.
+ *
+ * @param {unknown} value - The declared `books`.
+ * @param {string} rootDir - What a path resolves against.
+ * @param {string} contentPackage - The head of a default file stem.
+ * @returns {readonly Readonly<ResolvedPdfBook>[]} The books, frozen.
+ */
+function normalizePdfBooks(value, rootDir, contentPackage) {
+    if (value === undefined) {
+        fail("pdf.books", "is required — list the books this package publishes, one entry each");
+    }
+    if (!Array.isArray(value) || value.length === 0) {
+        fail("pdf.books", "must be a non-empty list of books");
+    }
+    const ids = new Set();
+    /** @type {Map<string, number>} Stem → the book that took it. */
+    const stems = new Map();
+    return Object.freeze(
+        value.map((entry, i) => {
+            const where = `pdf.books[${i}]`;
+            if (!isPlainObject(entry)) fail(where, "must be a mapping");
+            const book = /** @type {Record<string, unknown>} */ (entry);
+            rejectUnknownKeys(book, PDF_BOOK_KEYS, `${where}.`);
+
+            const id = requireNonEmptyString(book.id, `${where}.id`);
+            if (!PDF_BOOK_ID.test(id)) {
+                fail(
+                    `${where}.id`,
+                    `is \`${id}\`, which is not lowercase letters, digits and hyphens ` +
+                        `starting with a letter or digit (${PDF_BOOK_ID.source}) — it is ` +
+                        "written as `--book <id>` and ends the book's default file name",
+                );
+            }
+            if (ids.has(id)) fail(`${where}.id`, `is \`${id}\`, which names a book more than once`);
+            ids.add(id);
+            const title = requireNonEmptyString(book.title, `${where}.title`);
+
+            // One tree, from exactly one place: two would leave the reader to
+            // guess which is printed, and none prints nothing.
+            if ((book.contents === undefined) === (book.document === undefined)) {
+                fail(
+                    where,
+                    "must declare exactly one of `contents` and `document` — the tree " +
+                        "written inline, or the file holding it",
+                );
+            }
+            let contents = null;
+            if (book.contents !== undefined) {
+                if (!Array.isArray(book.contents)) {
+                    fail(`${where}.contents`, "must be a list of sections");
+                }
+                contents = Object.freeze(structuredClone(book.contents));
+            }
+
+            const front = [];
+            if (book.front !== undefined) {
+                if (!Array.isArray(book.front)) {
+                    fail(`${where}.front`, "must be a list of markdown files");
+                }
+                book.front.forEach((file, j) => {
+                    front.push(
+                        path.resolve(rootDir, requireNonEmptyString(file, `${where}.front[${j}]`)),
+                    );
+                });
+            }
+
+            let out = `${contentPackage}-${id}`;
+            let stemAt = `${where}.id`;
+            if (book.out !== undefined) {
+                out = requireNonEmptyString(book.out, `${where}.out`);
+                stemAt = `${where}.out`;
+                if (!PDF_BOOK_STEM.test(out)) {
+                    fail(
+                        `${where}.out`,
+                        `is \`${out}\`, which is not a file stem — letters, digits, ` +
+                            "`.`, `_` and `-`, with no directory; the directory is `pdf.out`",
+                    );
+                }
+            }
+            const taken = stems.get(out);
+            if (taken !== undefined) {
+                fail(
+                    stemAt,
+                    `gives the file stem \`${out}\`, which \`pdf.books[${taken}]\` already ` +
+                        "uses — the second book would overwrite the first",
+                );
+            }
+            stems.set(out, i);
+
+            return Object.freeze({
+                id,
+                title,
+                subtitle:
+                    book.subtitle === undefined ?
+                        ""
+                    :   requireNonEmptyString(book.subtitle, `${where}.subtitle`),
+                coverImage:
+                    book.coverImage === undefined ?
+                        ""
+                    :   path.resolve(
+                            rootDir,
+                            requireNonEmptyString(book.coverImage, `${where}.coverImage`),
+                        ),
+                front: Object.freeze(front),
+                out,
+                contents,
+                document:
+                    book.document === undefined ?
+                        ""
+                    :   path.resolve(
+                            rootDir,
+                            requireNonEmptyString(book.document, `${where}.document`),
+                        ),
+            });
+        }),
+    );
+}
+
 /**
  * A dotted version string as the three-element tuple Foundry compares.
  *
@@ -2551,15 +2679,6 @@ function normalizePublish(value) {
         fail("publish.address", "must be an object");
     }
     const address = /** @type {Record<string, unknown>} */ (addressInput ?? {});
-    // A retired key is refused by name, ahead of the vocabulary check: reported
-    // as merely unrecognized it would read as a misspelling of the one key that
-    // survives, and the author would correct the spelling rather than learn
-    // that the mechanism is gone.
-    for (const key of Object.keys(address)) {
-        if (Object.hasOwn(RETIRED_ADDRESS_KEYS, key)) {
-            fail(`publish.address.${key}`, RETIRED_ADDRESS_KEYS[key]);
-        }
-    }
     rejectUnknownKeys(address, ADDRESS_KEYS, "publish.address.");
 
     const prefix =
@@ -2799,6 +2918,7 @@ export function defineConfig(config) {
         new Set([...itemTypes, ...ACTOR_TYPES, "macro", ...MAP_TYPES]),
     );
     const compatibility = normalizeCompatibility(input.compatibility, "compatibility");
+    const authors = normalizeAuthors(input.authors);
     if (!documentation && compatibility === null)
         fail("compatibility.minimum", "is required for a Foundry package");
 
@@ -2813,7 +2933,8 @@ export function defineConfig(config) {
         // `checkHomepage` in `config.mjs`.
         homepage:
             input.homepage === undefined ? null : requireNonEmptyString(input.homepage, "homepage"),
-        author: normalizeAuthor(input.author),
+        authors,
+        author: bylineOf(authors),
         packageKind: /** @type {PackageKind} */ (packageKind),
         // Foundry serves a package's files from `<kind>/<id>/`, so this is the
         // one place `systems/sohl` (or `modules/harn-ensemble`) is spelled.
@@ -2883,7 +3004,9 @@ export function defineConfig(config) {
         packDirectories: Object.freeze(packDirectories),
         docs: normalizeDocs(input.docs),
         site: normalizeSite(input.site),
-        pdf: normalizePdf(input.pdf, rootDir),
+        // Validated above, in `contentPackage`: a book's default file stem is
+        // `<contentPackage>-<id>`.
+        pdf: normalizePdf(input.pdf, rootDir, /** @type {string} */ (input.contentPackage)),
         compatibility,
         relationships: normalizeRelationships(input.relationships),
         systems,