@heroiclands/package-build 22.15.0 → 22.16.0

package/engine/sql-tables.mjs

@@ -27,15 +27,17 @@
  */
 
 import { parseAddress, renderAddress, isAddressTuple } from "./address.mjs";
-import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { NOTE_VOCABULARY, isGmNote } from "./note-vocabulary.mjs";
 import { encodeAddresses } from "./address-values.mjs";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 import { FENCE_LINE, parseHeaderArgs } from "./code-fences.mjs";
+import { booleanAttribute } from "./extension-attributes.mjs";
 import { MARKET_CLASSES } from "./market-class.mjs";
 import { parseMarkdownFile } from "./helpers.mjs";
+import { sqlQueriesInMarkdown } from "./markdown-expressions.mjs";
 // The record accessors only — see `engine/index-records.mjs`.
 import { isNoteRecord, noteFile, sortKeysDeep } from "./index-records.mjs";
 
@@ -79,7 +81,7 @@ export function findSqlBlocks(markdown) {
         const closer = new RegExp(`^[ \\t]*${marker[0]}{${marker.length},}[ \\t]*$`);
         let close = i + 1;
         while (close < lines.length && !closer.test(lines[close])) close += 1;
-        const { language, args } = parseHeaderArgs(info);
+        const { language, args, problems } = parseHeaderArgs(info);
         if (language !== "sql") {
             // Not ours, but still a fence: skip its body so a `sql` line inside
             // some other block is never read as a directive.
@@ -87,20 +89,30 @@ export function findSqlBlocks(markdown) {
             continue;
         }
         if (close >= lines.length) continue;
-        const level = Number(args["section-level"]);
+        const level = Number(args["section-level"] ?? 2);
+        const errors = [...problems];
+        for (const key of Object.keys(args)) {
+            if (!["allow-empty", "section-level"].includes(key))
+                errors.push(`${key} is not an SQL fence attribute`);
+        }
+        let allowEmpty = false;
+        if (Object.hasOwn(args, "allow-empty")) {
+            try {
+                allowEmpty = booleanAttribute(args["allow-empty"], "allow-empty");
+            } catch (error) {
+                errors.push(error.message);
+            }
+        }
+        if (!Number.isInteger(level) || level < 1 || level > 6)
+            errors.push("section-level needs an integer from 1 through 6");
         blocks.push({
             line: i,
             close,
             indent,
             query: lines.slice(i + 1, close).join("\n"),
-            // `:allow-empty` says a table selecting nothing is intended.
-            // Spelled on the fence rather than in the query because it is a
-            // statement about this directive and not part of SQL.
-            allowEmpty: args["allow-empty"] === true,
-            sectionLevel: Number.isInteger(level) && level >= 1 && level <= 6 ? level : 2,
-            // Every header argument, so a caller can read one this module makes
-            // no use of — the point of taking a real grammar rather than a
-            // regex per property.
+            allowEmpty,
+            sectionLevel: level,
+            problems: errors,
             args,
             block: lines.slice(i, close + 1).join("\n"),
         });
@@ -150,10 +162,16 @@ export function findSqlBlocks(markdown) {
  * @param {string} [opts.dir] - Directory for the temporary file.
  * @param {Array<{id: string, file: string}>} [opts.dependencies] - Each
  *   declared dependency's cached index, attached as a schema named `id`.
+ * @param {object} [opts.addressContext] - Address resolution context.
+ * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes from
+ *   local and dependency relations.
  * @returns {Promise<{query: (sql: string) => Promise<object[]>,
  *   close: () => Promise<void>}>} The open database.
  */
-export async function openNotesDatabase(records, { dir, dependencies = [], addressContext } = {}) {
+export async function openNotesDatabase(
+    records,
+    { dir, dependencies = [], addressContext, audience = "all" } = {},
+) {
     const { DuckDBInstance } = await import("@duckdb/node-api");
     const base = dir ?? fs.mkdtempSync(path.join(os.tmpdir(), "content-sql-"));
     fs.mkdirSync(base, { recursive: true });
@@ -166,7 +184,7 @@ export async function openNotesDatabase(records, { dir, dependencies = [], addre
     const instance = await DuckDBInstance.create(":memory:");
     const connection = await instance.connect();
     await connection.run("SET threads=1");
-    await createRelations(connection, jsonl);
+    await createRelations(connection, jsonl, "", audience);
 
     // One schema per declared dependency, so `FROM sohl.notes` reads the notes
     // that package published. Quoted, because a package id may carry a hyphen
@@ -176,7 +194,7 @@ export async function openNotesDatabase(records, { dir, dependencies = [], addre
         if (!dep?.id || !dep?.file || !fs.existsSync(dep.file)) continue;
         const schema = `"${String(dep.id).replace(/"/g, '""')}"`;
         await connection.run(`CREATE SCHEMA IF NOT EXISTS ${schema}`);
-        await createRelations(connection, dep.file, `${schema}.`);
+        await createRelations(connection, dep.file, `${schema}.`, audience);
     }
 
     // The market scale as a relation, so a table prints `village` beside the
@@ -320,7 +338,7 @@ const WITH_STUBS_SCHEMA = "__with_stubs";
  * @param {string} [prefix] - A schema to qualify the view names with.
  * @returns {Promise<void>}
  */
-async function createRelations(connection, file, prefix = "") {
+async function createRelations(connection, file, prefix = "", audience = "all") {
     const read = readJsonAuto(file);
     const described = await connection.runAndReadAll(`DESCRIBE ${read}`);
     const columns = new Set(described.getRowObjects().map((row) => String(row.column_name)));
@@ -335,10 +353,15 @@ async function createRelations(connection, file, prefix = "") {
             "COALESCE(list_contains(TRY_CAST(tags AS VARCHAR[]), 'draft'), false) " +
             "OR COALESCE(TRY_CAST(tags AS VARCHAR) = 'draft', false)"
         :   "false";
+    const visible =
+        audience === "public" && columns.has("tags") ?
+            "NOT (COALESCE(list_contains(TRY_CAST(tags AS VARCHAR[]), 'gm'), false) " +
+            "OR COALESCE(TRY_CAST(tags AS VARCHAR) = 'gm', false))"
+        :   "true";
     await connection.run(
         `CREATE VIEW ${prefix}entries AS SELECT *, ` +
             `CASE WHEN ${stub} THEN 'stub' WHEN ${draft} THEN 'draft' ` +
-            `ELSE 'full' END AS state FROM (${read})`,
+            `ELSE 'full' END AS state FROM (${read}) WHERE ${visible}`,
     );
     await connection.run(
         `CREATE VIEW ${prefix}notes AS SELECT * FROM ${prefix}entries WHERE state <> 'stub'`,
@@ -467,6 +490,7 @@ function cellText(value, column) {
  * @param {(ref: string) => boolean} [opts.linkable] - Whether an address can be
  *   linked to; defaults to linking any non-empty `_ref`.
  * @param {number} [opts.sectionLevel=2] - Heading level for `_section`.
+ * @param {object} [opts.addressContext] - Address resolution context.
  * @returns {string} The markdown.
  */
 export function renderSqlTable(
@@ -563,6 +587,7 @@ export async function prepareSqlTables(db, sources, { linkable } = {}) {
         prepared.set(source, forNote);
         for (const block of blocks) {
             try {
+                if (block.problems.length) throw new Error(block.problems.join("; "));
                 const result = await runSqlQuery(db, block.query);
                 forNote.push({
                     markdown: renderSqlTable(result, {
@@ -589,6 +614,42 @@ export async function prepareSqlTables(db, sources, { linkable } = {}) {
     return prepared;
 }
 
+/** Evaluate scalar SQL calls before synchronous Markdown renderers run. */
+export async function prepareInlineSqlExpressions(db, sources) {
+    const byNote = new Map();
+    const cache = new Map();
+    for (const { source, markdown, frontmatter } of sources) {
+        const queries = sqlQueriesInMarkdown(markdown, frontmatter);
+        if (!queries.length) continue;
+        const values = new Map();
+        byNote.set(source, values);
+        for (const query of queries) {
+            if (!cache.has(query)) {
+                try {
+                    const result = await db.query(query);
+                    if (result.columnNames.length !== 1 || result.rows.length !== 1)
+                        throw new RangeError("scalar SQL needs exactly one column and one row");
+                    const value = result.rows[0][result.columnNames[0]];
+                    if (value === null || value === undefined || value === "")
+                        throw new RangeError("scalar SQL result is empty");
+                    if (
+                        value !== null &&
+                        !["string", "number", "boolean", "bigint"].includes(typeof value)
+                    )
+                        throw new TypeError(
+                            "scalar SQL result must be a number, string, Boolean, or null",
+                        );
+                    cache.set(query, { value });
+                } catch (error) {
+                    cache.set(query, { error: String(error?.message ?? error).split("\n")[0] });
+                }
+            }
+            values.set(query, cache.get(query));
+        }
+    }
+    return byNote;
+}
+
 /**
  * Answer every `sql` directive in a content tree.
  *
@@ -609,16 +670,22 @@ export async function prepareSqlTables(db, sources, { linkable } = {}) {
  * @param {object[]} [opts.records] - Index records the caller already derived.
  *   A command that also builds a link index holds them already, and deriving
  *   them twice is the duplicated-corpus failure this closes.
+ * @param {"all"|"public"} [opts.audience] - Whether to exclude GM notes.
  * @returns {Promise<Map<string, object[]>|undefined>} Results by note path, or
  *   nothing when the tree has no such directive.
  */
-export async function prepareTreeSqlTables(contentBase, { config, skipDirectories, records } = {}) {
+export async function prepareTreeSqlTables(
+    contentBase,
+    { config, skipDirectories, records, audience = "all" } = {},
+) {
     // Imported here rather than at module scope: the index reaches the pack
     // compilers through `manifest-emit` → `journals`, so a static import from a
     // module they load would close a cycle and leave `BasePackCompiler`
     // uninitialised for whichever module the runtime happened to load first.
     const { indexRecordsFor } = await import("./content-index.mjs");
-    const indexRecords = records ?? indexRecordsFor({ contentBase, config, skipDirectories });
+    const indexRecords = (
+        records ?? indexRecordsFor({ contentBase, config, skipDirectories })
+    ).filter((record) => audience !== "public" || !isGmNote(record));
 
     // Which notes carry a directive, discovered over the same corpus every
     // other pass reads rather than over a walk of this one's own. The
@@ -633,8 +700,9 @@ export async function prepareTreeSqlTables(contentBase, { config, skipDirectorie
     for (const record of indexRecords) {
         if (!isNoteRecord(record)) continue;
         const absPath = noteFile(contentBase, record);
-        const { body } = parseMarkdownFile(absPath);
-        if (body && findSqlBlocks(body).length) sources.push({ source: absPath, markdown: body });
+        const { body, frontmatter } = parseMarkdownFile(absPath);
+        if (body && (findSqlBlocks(body).length || sqlQueriesInMarkdown(body, frontmatter).length))
+            sources.push({ source: absPath, markdown: body, frontmatter });
     }
     if (!sources.length) return undefined;
     // A cell links only where the address it would emit resolves, so a table
@@ -664,11 +732,13 @@ export async function prepareTreeSqlTables(contentBase, { config, skipDirectorie
     } catch {
         dependencies = [];
     }
-    const db = await openNotesDatabase(indexRecords, { dependencies });
+    const db = await openNotesDatabase(indexRecords, { dependencies, audience });
     try {
-        return await prepareSqlTables(db, sources, {
+        const prepared = await prepareSqlTables(db, sources, {
             linkable: (ref) => addresses.has(renderAddress(ref)),
         });
+        prepared.inline = await prepareInlineSqlExpressions(db, sources);
+        return prepared;
     } finally {
         await db.close();
     }

package/engine/web-wikilinks.mjs

@@ -123,19 +123,8 @@ function lookupRead(index, read, contentPackage) {
 /**
  * How an **unresolved** link renders.
  *
- * The author's text is kept, so the sentence still reads — dropping it would
- * silently rewrite the prose. It is marked so a reader can tell that something
- * was meant to be a link, and an author can find it: the appearance lives in
- * `scss/components/_unresolved-link.scss` for Foundry and in the Hugo theme for
- * the website, not here.
- *
- * This is deliberately identical to the pack compiler's own `unresolvedLink`,
- * down to the class name and the `title` wording. One authored link renders on
- * two surfaces, and the two builds have drifted before over exactly this kind
- * of detail — matching markup is what keeps a reader's cue the same in
- * a journal and on the page. Duplicated rather than imported only because the
- * function is not exported from `@heroiclands/package-build`; hoisting it there
- * is.
+ * The author's text remains readable. The website uses an HTML span matching
+ * the pack compiler's cue; the book uses text that Typst can print.
  *
  * The knowledgebase renders with `unsafe = true` (`kb/hugo.toml`), so raw HTML
  * in generated markdown reaches the page. That makes escaping obligatory: this
@@ -143,9 +132,11 @@ function lookupRead(index, read, contentPackage) {
  *
  * @param {string} text - The text to show, from the link's label or target.
  * @param {string} target - The address that resolved nowhere, for the tooltip.
- * @returns {string} An inline HTML span, safe to sit in a markdown table cell.
+ * @param {"html"|"book"} output - The destination format.
+ * @returns {string} A visible cue in the destination's Markdown.
  */
-function unresolvedLink(text, target) {
+function unresolvedLink(text, target, output) {
+    if (output === "book") return `${text} (unresolved link)`;
     const esc = (v) =>
         String(v)
             .replace(/&/g, "&")
@@ -159,27 +150,18 @@ function unresolvedLink(text, target) {
 }
 
 /**
- * How a link to a **draft** note renders.
+ * How the website marks a link to a **draft** note.
  *
  * A note tagged `draft` exists so a link into it is not dead, and nothing more.
  * Unmarked, a reader follows a promising link into an empty page and an author
  * cannot see which of their links still owe content.
  *
- * **The wrapper carries the cue and nothing else.** The link itself is
- * untouched — Goldmark parses inline markdown inside an inline HTML span, so
- * the markdown link still becomes an anchor, and the note is on the site, in
- * the packs and in the manifest exactly as any other. Nothing here resembles
- * the retired `draft:` field, which moved a note from published to unresolvable
- * without saying so.
+ * The link itself remains intact inside the HTML span.
  *
  * The appearance lives in the Hugo theme for the website and in
  * `scss/components/_draft-link.scss` for Foundry, not here.
  *
- * **Byte-identical with the pack build's copy** in `wikilinks.mjs`, down to the
- * class name and the `title` wording — one authored link renders on two
- * surfaces, and the two builds have drifted before over exactly this kind of
- * detail. Duplicated rather than imported for the same reason
- * {@link unresolvedLink} is; hoisting both is.
+ * The website span matches the pack compiler's copy in `wikilinks.mjs`.
  *
  * The argument is already-built markup and is deliberately not escaped; the
  * *authored* text inside it was escaped, or made into a link, by the caller.
@@ -322,7 +304,8 @@ function isPlainMap(value) {
  *
  * @param {string} body - The markdown body.
  * @param {object} ctx - `{ index, assets, collide, contentTypes,
- *   packages, noIndexPackages, foreign, type, errors, src, file, resolved }`.
+ *   packages, noIndexPackages, foreign, type, errors, src, file, resolved,
+ *   output }`. `output` is `"book"` for PDF Markdown and defaults to HTML.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type;
  *   `noIndexPackages` is every package declared `contentIndex: false`, so a
@@ -373,7 +356,7 @@ export function resolveWebWikilinks(body, ctx) {
      */
     const report = (all, finding, text) => {
         record(all, finding);
-        return unresolvedLink(text, finding.target);
+        return unresolvedLink(text, finding.target, ctx.output ?? "html");
     };
 
     // An embed names a file, so it resolves before anything looks for a link.
@@ -416,7 +399,7 @@ export function resolveWebWikilinks(body, ctx) {
 
         // `[[#section-slug|Text]]` — a section of this same page.
         if (isSamePage({ target, anchor })) {
-            return `[${label ?? anchor}](#${slugify(anchor)})`;
+            return `[${label ?? ctx.captionLabels?.get(anchor) ?? anchor}](#${slugify(anchor)})`;
         }
 
         // The canonical separator has to be resolved, not merely
@@ -455,7 +438,8 @@ export function resolveWebWikilinks(body, ctx) {
             // Presentation only — the href above is unchanged, and a
             // `[[#anchor]]` self-link is not marked because the reader is
             // already on the page it would be telling them about.
-            return hit.draft ? draftLink(link) : link;
+            if (!hit.draft) return link;
+            return ctx.output === "book" ? `${link} (draft)` : draftLink(link);
         }
 
         // **An address resolving nowhere is a failure, unconditionally**.

package/engine/wikilink-syntax.mjs

@@ -203,6 +203,7 @@ export const LINK_FINDING_REASONS = Object.freeze(
         "not-an-asset",
         "unresolved",
         "stub",
+        "gm",
         "ambiguous",
         "unknown-anchor",
         "no-content-index",
@@ -232,7 +233,7 @@ export function unresolvedAddressMessage(target) {
     return (
         `address [[${target}]] resolves to no note — no package publishes ` +
         `it. Fix the shortcode, or declare the package that does as a ` +
-        `dependency and run \`content-build deps fetch\``
+        `dependency and run \`package-build deps fetch\``
     );
 }
 
@@ -344,6 +345,8 @@ export function linkFindingMessage({ reason, target, packages, anchor, type, stu
             return unresolvedAddressMessage(target);
         case "stub":
             return stubAddressMessage(target, stub);
+        case "gm":
+            return `address [[${target}]] names a GM-only note from a player-facing note`;
         case "no-content-index":
             return (
                 `address [[${target}]] names a package declared \`contentIndex: false\` — ` +

package/engine/wikilinks.mjs

@@ -121,6 +121,8 @@ export function anchorPageId(noteId, anchorSlug) {
  *   `contentIndex: false` — a Foundry dependency only. A link naming one fails
  *   with `no-content-index` rather than resolving, ambiguously, as either a
  *   typo or an undeclared package.
+ * @param {Map<string, object>} [opts.referenceTargets] - Local reference targets.
+ * @param {Map<string, object>} [opts.foreignReferences] - Foreign reference targets.
  * @returns {{byShortcode: Map<string, object>, types: Set<string>}} `types` is
  *   every type the tree actually contains, so a qualifier naming no real type
  *   can be told apart from a missing target.
@@ -158,11 +160,9 @@ export function buildWikilinkIndex(
 
         uuidByDoc.set(
             d,
-            // A note declaring `pack: none` compiles into no document, so it
-            // has no address in any compendium: a link to it is a page on the
-            // web and prose in a journal. Recorded as an entry with no UUIDs
-            // rather than left out, so the address still resolves and a link
-            // to it is never reported as dead.
+            // A note with no single Foundry document has no compendium UUID:
+            // a link to it retains its label in a journal. Keep the indexed
+            // address so the link resolves without a dead-link finding.
             d.none ?
                 { uuid: undefined, docUuid: undefined }
             :   {
@@ -375,6 +375,7 @@ function draftLink(inner) {
  *   entry landed in.
  * @param {{byShortcode: Map, types: Set}} ctx.index - From
  *   {@link buildWikilinkIndex}.
+ * @param {Map<string, string>} [ctx.captionLabels] - Numbered caption references.
  * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
  *   offset: number, reason: string, packages?: string[], anchor?: string}>}}
  *   Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all
@@ -383,7 +384,7 @@ function draftLink(inner) {
  *   position in `markdown`, which is what lets a caller report the line and
  *   column it sits on.
  */
-export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
+export function convertWikilinks(markdown, { type, id, pack, docPack, index, captionLabels }) {
     const unresolved = [];
 
     // `offset` is the third replacer argument because the pattern has exactly
@@ -512,7 +513,8 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
         // the document's **current** name stands in and a rename shows at every
         // citation with no link edited. The knowledgebase build reads
         // the same authored link the same way.
-        if (!text) text = doc.name ?? target;
+        if (!text)
+            text = (target === "" && slug ? captionLabels?.get(slug) : null) ?? doc.name ?? target;
 
         // Both addresses were computed when the target was indexed. An item
         // doc lives in the journals pack under its own derived entry id, and
@@ -526,12 +528,8 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
             docUuid: compendiumUuid(index.packageId, "doc", itemDocEntryId(doc.id), doc.docPack),
         };
         const entryUuid = itemDoc ? addresses.docUuid : addresses.uuid;
-        // The target is a note that compiles into no document — `pack: none`.
-        // The address is real and the page exists on the web, so this is not
-        // a dead link and must not fail the build; but a compendium has
-        // nothing to open, so the reader gets the prose and no `@UUID`. The
-        // mirror of what the website does for an address that publishes a
-        // document and no page.
+        // The target has no single Foundry document. Its address is real, but
+        // a compendium has nothing to open, so the reader gets the label.
         if (entryUuid === undefined) return text;
         const entryId = itemDoc ? itemDocEntryId(doc.id) : doc.id;
         const isJournal = itemDoc || packForType(doc.type).docType === "JournalEntry";
@@ -542,7 +540,7 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
         // can never hold one is what made such links dead-end; an
         // an item's pages are addressed through its `note` Address.
         // A `#section` the target declares no heading for. Checked here, and
-        // not only by `content-build links`, because this is the build that
+        // not only by `package-build links`, because this is the build that
         // *emits* the link: `anchorPageId` will hash any slug into a page id,
         // so an undeclared one compiles to a `@UUID` that dead-ends for the
         // reader. A foreign anchor has always been checked this way —

package/hm3/item-fields.mjs

@@ -40,7 +40,7 @@
  * are written bare, exactly as SoHL's are: the `data:` region is the sweep's
  * migration and neither half has moved to it. Spelling HM3's differently would
  * make a note feeding both systems author the same fact twice for no gain, and
- * would take these rows out of reach of `content-build content-format fields`,
+ * would take these rows out of reach of `package-build content-format fields`,
  * which pairs a `data.<key>` claim with a bare declared `<key>`. Both halves
  * move together when the sweep lands.
  *

package/hm3/items.mjs

@@ -12,44 +12,14 @@
  */
 
 /**
- * **HM3's Item pass** — the two things about compiling a note into an HM3 Item
- * that are facts about HM3 rather than about the note format.
- *
- * Everything else is {@link module:engine/item-compiler}'s, and is the same
- * code the SoHL pass runs: which notes are claimed, which subtype each becomes,
- * which registry builds it, the authored `hm3.system` passthrough, the schema
- * check, and the compendium envelope. A second system is a map and a handful of
- * emitted keys, which is the arrangement the mapping tables build towards.
- *
- * **What HM3's compiler writes on every item: one key, and only when there is
- * something to write.** The content format gives an item's `{#appearance}`
- * section a home in HM3 — `description` — and SoHL none, since no SoHL Item
- * subtype declares such a field. So the section is rendered here and nowhere
- * else. Where a note has no such section nothing is emitted at all, which
- * matters for `armorlocation`: it is the one HM3 subtype that extends the
- * Foundry base directly, declaring neither `description` nor `notes`, so an
- * unconditional key would be a finding on every armour-location document in the
- * pack.
- *
- * **And one flag, for the fact HM3's `system` has no field for.** The template
- * priority is a shared statement — a note declaring `data.templatePriority` says
- * the same thing to both systems — but HM3 declares no `system` field for it, so
- * it lands under this system's own flag scope as `flags.hm3.templatePriority`,
- * exactly as the Actor pass writes it. Without it, an item note declaring the
- * priority compiles into a SoHL item that knows it is a template and an HM3
- * item that does not.
- *
- * **There is no HM3 equivalent of `docHtml`.** SoHL points an item at the
- * JournalEntry its prose compiled into, and HM3's data model has nowhere to put
- * such a pointer; inventing one would emit a key Foundry discards at load
- * without a word. The prose still compiles into its JournalEntry — the journals
- * pass claims every doc-carrying type regardless of system — it simply is not
- * addressed from the item.
+ * HM3's Item compiler uses the shared note-to-Item pass. It puts the pointer
+ * to the note's `{#description}` JournalEntryPage in `system.description` when
+ * the Item subtype declares that field. `armorlocation` has no description.
+ * The shared `data.templatePriority` is recorded in HM3 flags.
  *
  * @module
  */
 
-import { renderSection } from "../engine/anchored-sections.mjs";
 import { SystemItemCompiler } from "../engine/item-compiler.mjs";
 import { HM3_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 import { templateFlags } from "./template-priority.mjs";
@@ -58,7 +28,7 @@ import { templateFlags } from "./template-priority.mjs";
  * HM3's Item compile pass.
  *
  * Declares HM3's note-type → document-subtype map, which decides the notes this
- * pass claims and what each becomes, the one `system` key HM3 writes from prose,
+ * pass claims and what each becomes, the one `system` key HM3 writes as a page pointer,
  * and the template-priority flag HM3's data model has no field for. Everything
  * else is {@link module:engine/item-compiler}'s.
  */
@@ -74,28 +44,25 @@ export class Hm3Items extends SystemItemCompiler {
     /**
      * The `system` keys this pass derives from the note.
      *
-     * `description` is the note's `{#appearance}` section, rendered. A note
-     * authoring it writes into a key the compiler overwrites from prose that
-     * may say something else.
+     * `description` points to the note's `{#description}` page. A note
+     * authoring it writes into a key the compiler derives from the shared body.
      *
      * @type {readonly {key: string, from: string}[]}
      */
     static derivedSystemKeys = Object.freeze([
-        { key: "description", from: "the note's `{#appearance}` section" },
+        { key: "description", from: "the note's `{#description}` page" },
     ]);
 
     /**
-     * The `system.*` field HM3 writes on an item from the note's prose.
+     * The `system.*` field HM3 writes from the shared item-doc pointer.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {object} at - What the pass already knows about this note.
-     * @param {string} at.markdown - The note body, tables expanded and
-     *   wikilinks resolved.
+     * @param {string} at.description - The resolved JournalEntryPage pointer.
      * @returns {object} The shared `system` fields — `description`, or nothing.
      */
-    commonSystem(fm, { markdown }) {
-        const description = renderSection(markdown, "appearance");
-        return description ? { description } : {};
+    commonSystem(fm, { description }) {
+        return description && this.itemSubtype(fm) !== "armorlocation" ? { description } : {};
     }
 
     /**

package/index.mjs

@@ -15,20 +15,8 @@
  * `@heroiclands/package-build` — the shared toolchain for building and shipping
  * a HeroicLands **Foundry package**, content and all.
  *
- * This package was two: `content-build`, which read `assets/content/**` and
- * produced compendium packs, site content and the link manifest, and this one,
- * which read `lang/`, `styles/`, `src/` and the manifest template. They were
- * split by *input* on the theory that a module would use either — an adventure
- * shipping only notes needs no bundler, a variant shipping only behavior needs
- * no Markdown pipeline.
- *
- * **No consumer ever used one alone.** All three installed both, and this
- * package depended on the other besides, so the packaging half dragged the
- * content half in regardless. What the boundary actually cost was a
- * configuration file with two owners, two CLIs with a colliding `manifest`
- * command, and a two-repository dance for changes that touched one idea. The
- * two halves are now one package; the split survives as the shape of this
- * barrel and nothing more.
+ * Content and package operations share one configuration and one CLI. The
+ * exports here provide library entry points for both kinds of work.
  *
  * **Everything exported here is pure.** Functions take source text and return
  * findings or values; discovery, I/O and reporting stay with the caller. That

package/manifest.mjs

@@ -52,7 +52,7 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 
-import { emitDiagnostic, positionOfYamlPath } from "./engine/diagnostics.mjs";
+import { emitDiagnostic, formatDiagnostic, positionOfYamlPath } from "./engine/diagnostics.mjs";
 import { metadataFileName } from "./engine/metadata-index.mjs";
 
 /**
@@ -393,7 +393,7 @@ export function packFolderFindings({ packFolders, packs = [] }) {
  * package.
  *
  * `relationships` is the one manifest block with a second reader.
- * `@heroiclands/content-build` consumes it too, and v1.8.0 added
+ * `@heroiclands/package-build` consumes it too, and v1.8.0 added
  * `itemCatalog: true` as an opt-in on a declared dependency: it selects that
  * package's Item packs as a resolution
  * source for the actors pass. That is an instruction to the build, not a fact
@@ -408,7 +408,7 @@ export function packFolderFindings({ packFolders, packs = [] }) {
  * unlikely to be the last.
  *
  * A list is enough, and needs no prefix agreed between the two packages,
- * because the input is already closed: content-build normalises a relationship
+ * because the input is already closed: package-build normalises a relationship
  * to `id`, `type`, `manifest`, `compatibility` and its own build keys, and
  * rejects anything else at configuration time. A key that reaches here is one
  * the toolchain itself put there.
@@ -429,7 +429,7 @@ export const BUILD_ONLY_RELATIONSHIP_KEYS = Object.freeze(["itemCatalog"]);
  * unread: a key Foundry adds later should not need a release of this package.
  *
  * @param {Record<string, unknown>} relationships - The declared block, as
- *   content-build resolved it.
+ *   package-build resolved it.
  * @returns {Record<string, unknown>} It, without the build-only keys.
  */
 export function publishedRelationships(relationships) {
@@ -455,6 +455,13 @@ function withoutBuildKeys(entry) {
     );
 }
 
+/** Require the displayed identity Foundry needs to install the package. */
+function requireManifestTitle(config) {
+    const title = config.packageBuild?.manifest?.title;
+    if (typeof title !== "string" || title.trim() === "")
+        throw new Error("`packageBuild.manifest.title` must be a non-empty string.");
+}
+
 /**
  * Build a Foundry package manifest from the resolved configuration.
  *
@@ -483,6 +490,7 @@ function withoutBuildKeys(entry) {
  * @returns {object} The manifest, ready to serialise.
  */
 export function buildManifest({ config, packageJson, artifact, flags }) {
+    requireManifestTitle(config);
     // `descriptionHtml` is the authored source of `description` — pulled out
     // so it never survives the spread below under its own name.
     const { descriptionHtml, ...declared } = config.packageBuild?.manifest ?? {};
@@ -641,6 +649,25 @@ function reportPackFolders(findings, configFile) {
  *   ship. Nothing is written in that case.
  */
 export async function writeManifest({ config, packageJson, artifact, outDir, flags, configFile }) {
+    try {
+        requireManifestTitle(config);
+    } catch (error) {
+        let text;
+        if (configFile) {
+            try {
+                text = fsSync.readFileSync(configFile, "utf8");
+            } catch {
+                text = undefined;
+            }
+        }
+        const message = formatDiagnostic({
+            ...(configFile ? { file: configFile } : {}),
+            ...(text ? positionOfYamlPath(text, ["packageBuild", "manifest"]) : {}),
+            severity: "error",
+            message: error.message,
+        });
+        throw Object.assign(new Error(message), { located: true });
+    }
     const manifest = buildManifest({ config, packageJson, artifact, flags });
 
     const errors = reportPackFolders(