@heroiclands/package-build 14.0.0 → 16.0.0

package/engine/field-reference.mjs

@@ -111,6 +111,34 @@ function fieldTable(fields) {
     return padTable(rows);
 }
 
+/**
+ * The fields of one type that are **not** filled from the note's top level.
+ *
+ * A field ordinarily falls back to the top-level property spelled like its
+ * name, so an author who writes `weight: 3` at the top of a note reasonably
+ * expects it to reach the document. Where that spelling means something else at
+ * the note level the fallback is off, and an author has no way to tell from the
+ * table — the field is there, the value is written, and the document ships the
+ * default. So the reason each such field declares is rendered beside its table
+ * rather than left in the source (#218).
+ *
+ * Below the table, not inside it: the reason is a sentence or two, and
+ * {@link padTable} pads every column to its widest cell, so a cell holding it
+ * would stretch the whole type's table past legibility.
+ *
+ * @param {readonly object[]} fields - The type's declaration.
+ * @returns {string[]} Markdown lines, empty when the type exempts nothing.
+ */
+function sharedExemptions(fields) {
+    const exempt = authoredFields(fields).filter((field) => field.topLevelMeans);
+    if (!exempt.length) return [];
+    return exempt.flatMap((field) => [
+        `**\`${field.name}\` is not read from the note's top level.** There it means ` +
+            `${field.topLevelMeans}`,
+        "",
+    ]);
+}
+
 /**
  * A minimal note for one type: the frontmatter envelope every note carries,
  * plus exactly the `sohl:` fields the type requires.
@@ -204,6 +232,7 @@ export function renderItemFieldReference({
             "",
             ...fieldTable(declared[type]),
             "",
+            ...sharedExemptions(declared[type]),
             ...workedExample(type, declared[type]),
             "",
         );

package/engine/field-spec.mjs

@@ -65,6 +65,31 @@ export { setPath };
  *   still read, second, until #126 moves the corpus off it.
  *
  *   Absent means the value is not authored at all — see `value`.
+ * @property {string} [topLevelMeans] - **What the note's top-level key of this
+ *   name means instead** — declared only where it means something else, and
+ *   stating it removes the shared top-level position from this field's
+ *   resolution order (#218).
+ *
+ *   A field's `name` doubles as its identity and as the shared property it
+ *   draws from, which is right wherever the two levels state the same quantity
+ *   — `data.weight` is the weight, whoever reads it. It is wrong wherever a
+ *   spelling collides across the two vocabularies. An `affiliation` item's
+ *   `system.title` is the style of address an office carries; a note's
+ *   top-level `title` is the note's own heading. Nothing relates them, and
+ *   before this key one silently fed the other, stringifying an authored
+ *   `title: null` into fifteen documents.
+ *
+ *   **The value is the reason**, not a flag with a comment beside it. A boolean
+ *   would record the decision and lose the case for it, and the next person
+ *   adding a field needs to know the question exists — this package's own rule
+ *   that the declaration *is* the statement, never a description of one. The
+ *   author-facing reference renders it, so an author reading the field table
+ *   learns that the top-level key will not fill this field, and why.
+ *
+ *   The exempted field is still authorable, at both of the positions that
+ *   describe the *document* rather than the note: `<system>.system.<to>` and
+ *   the legacy in-block `<system>.<name>`. Absent means the ordinary case —
+ *   the top level is read, as the third step.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
  * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -

package/engine/frontmatter-lint.mjs

@@ -56,7 +56,12 @@
  */
 
 import { authoredFields } from "./field-spec.mjs";
-import { resolveFieldValue, SYSTEM_BLOCK_KEYS, unknownBlockKeys } from "./system-block.mjs";
+import {
+    resolveFieldValue,
+    systemBlock,
+    SYSTEM_BLOCK_KEYS,
+    unknownBlockKeys,
+} from "./system-block.mjs";
 import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES } from "./ids.mjs";
@@ -461,6 +466,121 @@ function checkTags(note, { type }) {
     return findings;
 }
 
+/**
+ * The frontmatter fields that name artwork, and so resolve through
+ * {@link module:engine/helpers.resolveImg}.
+ *
+ * Both, always: a being carries `img` and `portrait` independently — the token
+ * art and the sheet portrait — and a rule about how the translator reads an
+ * empty value belongs to the translator, not to whichever key happens to be
+ * more common. Eleven `sohl-kethira-basic` beings write `portrait: ""` and no
+ * note in any tree writes `img: ""` on a being; a check keyed on `img` alone
+ * would have called that tree clean (#218).
+ *
+ * @type {readonly string[]}
+ */
+const ART_FIELDS = Object.freeze(["img", "portrait"]);
+
+/**
+ * Read a shared top-level field the way the compiler reads one: the `sohl:`
+ * block first, then the note's top level.
+ *
+ * The same order {@link module:engine/helpers.sohlField} uses, restated here
+ * rather than imported so this module stays a leaf the linter can load without
+ * a resolved build configuration. Unlike `sohlField` it distinguishes the two
+ * empties — an authored `""` comes back as `""` and an authored `null` as
+ * `null` — which is the whole point of the caller below (#218).
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} key - The field name.
+ * @returns {any} The authored value, or `undefined` where neither position
+ *   declares one.
+ */
+function authoredValue(fm, key) {
+    const block = fm?.sohl;
+    if (block && typeof block === "object" && !Array.isArray(block) && Object.hasOwn(block, key)) {
+        return block[key];
+    }
+    return fm && Object.hasOwn(fm, key) ? fm[key] : undefined;
+}
+
+/**
+ * Two embedded items on one actor may not share `(type, shortcode)` (#228).
+ *
+ * SoHL treats `(type, shortcode)` as a **logical identity**, not a lookup
+ * convenience: two documents of one type bearing one shortcode denote *the same
+ * entity*, whatever their `_id`s or field values. It is unique within four
+ * scopes, one of which is an actor's own embedded items — and the invariant
+ * exists to keep that identity well-defined. Two colliding entries make "the
+ * same thing" ambiguous, and every match resolving by it — compendium↔world
+ * reconciliation, archetype shadowing, `fvttFindItemByShortcode`, cohort
+ * membership, expression and effect references — becomes unsound.
+ *
+ * Nothing else catches it. The compiler resolves each entry independently and
+ * distinguishes the two only when seeding `_id`, so the collision compiles to
+ * two documents with distinct ids and ships unremarked.
+ *
+ * **Decidable from frontmatter alone**, which is why it belongs here rather
+ * than in the compiler. An entry's effective key is
+ * `system.shortcode ?? shortcode`: a top-level `shortcode` merely selects the
+ * template the entry is written from and is never written to the document,
+ * while a template's own `system.shortcode` is its address by construction. So
+ * neither the catalogue nor a compile is needed to know what an entry will
+ * carry.
+ *
+ * Only entries naming both a type and a key are compared. One naming neither —
+ * a stand-alone entry still missing its `system.shortcode` — is the compiler's
+ * finding to make, and reporting it twice helps nobody.
+ *
+ * @param {object} note - A note from the link index (`{fm, file, raw}`).
+ * @param {string} blockName - The system block whose `items` to check.
+ * @returns {object[]} One finding per collision, at the later entry.
+ */
+function checkEmbeddedShortcodes(note, blockName) {
+    const findings = [];
+    const block = systemBlock(note.fm ?? {}, blockName);
+    const entries = block?.items;
+    if (!Array.isArray(entries)) return findings;
+
+    /** `type\0key` → the index that claimed it first. */
+    const claimed = new Map();
+    entries.forEach((entry, index) => {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) return;
+        const type = entry.type;
+        const system = entry.system;
+        const key =
+            system && typeof system === "object" && !Array.isArray(system) ?
+                (system.shortcode ?? entry.shortcode)
+            :   entry.shortcode;
+        if (!type || !key) return;
+
+        const address = `${type}${key}`;
+        const first = claimed.get(address);
+        if (first === undefined) {
+            claimed.set(address, index);
+            return;
+        }
+        findings.push({
+            file: note.file,
+            ...positionOfFrontmatterPath(note.raw ?? "", [blockName, "items", index]),
+            severity: "error",
+            message:
+                `"${type}:${key}" is already the shortcode of ` +
+                `\`${blockName}.items[${first}]\` on this actor; ` +
+                `(type, shortcode) identifies *which entity* an item is, and ` +
+                `must be unique among an actor's embedded items, so the two ` +
+                `denote one thing and every lookup by it is ambiguous. Give ` +
+                `this entry its own \`system.shortcode\`` +
+                (entry.shortcode && !entry.system?.shortcode ?
+                    ` — a top-level \`shortcode\` only selects the template ` +
+                    `this entry is written from and never reaches the document`
+                :   "") +
+                `, or delete it if it is a duplicate.`,
+        });
+    });
+    return findings;
+}
+
 /**
  * Check one note against its type's schema.
  *
@@ -503,6 +623,53 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
                 "note in the tree belongs to it",
         });
     }
+    // `img: ""` was how a note said "I name no art" while `resolveImg`
+    // conflated the two empties and every caller defaulted with `||`. It now
+    // says the opposite — "ship no art, and do not default me" (#218) — so a
+    // note carrying the old spelling has quietly changed meaning. Forty-five
+    // `sohl-thalorna` notes were written under the old reading and would have
+    // lost their default art with no error and no warning; this is the guard
+    // that would have caught them.
+    //
+    // **Both art fields, because both go through `resolveImg`.** `portrait` is
+    // not a variant spelling of `img` — a being carries the two independently —
+    // and checking only the more common one is how the sweep that prompted this
+    // guard missed eleven `sohl-kethira-basic` beings that write
+    // `portrait: ""`. Whatever the rule is, it belongs to the function, not to
+    // one of the keys that reaches it.
+    //
+    // A **warning**, on the pattern the `package:` and retired-alias sweeps
+    // set: the note still compiles, to a document that is merely iconless, so
+    // reddening a tree over it would refuse before the sweep rather than after
+    // it. It is transitional in the same sense — `""` is a legal thing to mean,
+    // and the message says so, but nothing in any tree means it yet.
+    //
+    // **These two only, never `title`.** The rule reads as a general one about
+    // optional strings, and it is not — it belongs to `resolveImg`, and `title`
+    // never goes through it.
+    //
+    // It once had a sharper reason, recorded here because it was load-bearing
+    // and is now false: a note's top-level `title` was simultaneously the shared
+    // source for an `affiliation` item's `system.title`, so asking an author for
+    // `title: null` would have compiled the literal string `"null"` into the
+    // document. That collision is gone — the field declares `topLevelMeans` and
+    // the top-level key is no longer a source for it — so `title: null` is now
+    // harmless. Whether `title: ""` deserves a warning of its own is a separate
+    // question about the *page's* heading, still open on #218, and not settled
+    // by extending an art-path check to it.
+    for (const key of ART_FIELDS) {
+        if (authoredValue(fm, key) !== "") continue;
+        findings.push({
+            file: note.file,
+            ...at(key),
+            severity: "warning",
+            message:
+                `\`${key}: ""\` means "ship no art at all" — it no longer falls ` +
+                `back to this type's default. Write \`${key}: null\` for a note ` +
+                'that simply names none; keep `""` only where the document is ' +
+                "meant to have no image",
+        });
+    }
     if (Object.hasOwn(fm, "draft")) {
         findings.push({
             file: note.file,
@@ -647,6 +814,9 @@ export function lintNote(note, { schemas, index, vocabulary, systems = DEFAULT_S
     // for `sohl`, the note type's own field names, which are still the position
     // the corpus authors them at until #126 moves them.
     for (const [blockName, spec] of Object.entries(systems ?? {})) {
+        // Two embedded items denoting one entity (#228). Per block, because
+        // `items` is a block key and a second system's actor carries its own.
+        findings.push(...checkEmbeddedShortcodes(note, blockName));
         const accepted = new Set([
             ...UNIVERSAL_KEYS,
             ...(spec?.known ?? []),

package/engine/helpers.mjs

@@ -234,25 +234,51 @@ export function makeFilename(name, id) {
  * asset roots — `icons/...` and `images/...` — are served from the package
  * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
  * for this repository, `modules/<id>/assets` for a module (#1508). Any other
- * path (already package-rooted, an absolute URL) is returned unchanged, and an
- * empty path yields `""`.
- *
- * This is translation only: the per-type default for an empty result is
- * domain-specific (actors default differently from items, and gear differently
- * again), so each compiler owns its own default and applies it to the result —
- * `resolveImg(fm.img) || <default>`. For items that default is the art paired
- * with the type's builder, reached through `itemArt()`, which runs the path
- * back through this function so a registry entry and a note's `img:` are
- * spelled the same way (#7).
+ * path (already package-rooted, an absolute URL) is returned unchanged.
+ *
+ * **Two empties, and they mean opposite things (#218).** `null` — or an absent
+ * key, which reaches here as `undefined` — means _unset_: the note names no art
+ * and the caller's default applies. `""` means _blank on purpose_: the note
+ * names no art **and wants none**, so no default may replace it. Both come back
+ * distinguishable, `null` and `""` respectively, and neither is invented from
+ * the other.
+ *
+ * This used to open `if (!raw) return ""`, which made the two one case: every
+ * caller then applied its default with `||`, so a deliberate blank was
+ * unspellable and an unset key and an empty string compiled identically. That
+ * is the convention the project already rejects for an optional "not specified"
+ * DataModel string, where `nullable, initial: null` keeps "unset" a single
+ * honest value rather than two.
+ *
+ * **`title` does not follow this rule**, and must not be made to. On a
+ * `type: affiliation` note `title` is *also* a declared item field whose default
+ * is `""` (`sohl/item-fields.mjs`), resolved from the very same shared top-level
+ * key the site emitter reads as the page title — so `title: null` stringifies
+ * into the compiled document as the literal `"null"`. One key, two destinations
+ * that disagree about what empty means; see #218.
+ *
+ * This is translation only: the default for an unset path is domain-specific
+ * (actors default differently from items, and gear differently again), so each
+ * compiler owns its own default and applies it to the result with **nullish**
+ * coalescing — `resolveImg(fm.img) ?? <default>`. Not `||`: that would collapse
+ * a deliberate blank back into the default and undo the distinction. For items
+ * that default is the art paired with the type's builder, reached through
+ * `itemArt()`, which runs the path back through this function so a registry
+ * entry and a note's `img:` are spelled the same way (#7).
  *
  * @param {string | null | undefined} raw - content-relative path from frontmatter.
  * @param {{assetRoot: string}} [config] - The resolved build configuration.
  *   Defaults to this repository's.
- * @returns {string} the Foundry-relative path, or `""` when `raw` is empty.
+ * @returns {string | null} the Foundry-relative path; `""` for a deliberate
+ *   blank, and `null` when the note names no art at all.
  */
 export function resolveImg(raw, config = loadPackConfig()) {
-    if (!raw) return "";
+    // Unset — the caller's default applies. An absent key arrives as
+    // `undefined`, an authored one as `null`; they say the same thing.
+    if (raw == null) return null;
     const s = String(raw);
+    // Blank on purpose — the caller's default must not apply.
+    if (s === "") return "";
     if (s.startsWith("icons/") || s.startsWith("images/")) {
         return `${config.assetRoot}/${s}`;
     }

package/engine/homepage.mjs

@@ -371,6 +371,13 @@ export function homepageTitle(fm, config) {
  * for one; it decides nothing while `url` is present, but a page carrying only
  * `url` would report a slug Hugo had inferred from the filename.
  *
+ * **Site-root relative, and so carrying no package base** (#217), exactly as
+ * `pageFrontmatter` states a content page's: Hugo resolves a `url`
+ * against `baseURL`, whose path is already where the package is served, so a
+ * stated base was written twice and published the landing at
+ * `/<package>/<package>/homepage-root/`. Where the package is served is what
+ * every *href* is composed from and it reaches this page's address not at all.
+ *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
  * redirect stub at each one. The field is retired (#180) and refused before a
@@ -380,14 +387,12 @@ export function homepageTitle(fm, config) {
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
- * @param {string} options.base - Where the package is served, with both
- *   slashes — `/<package>/`.
  * @returns {object} The frontmatter to write.
  * @throws {Error} When the note declares no shortcode, and so has no address.
  */
-export function homepageFrontmatter(fm, { contentPackage, title, base }) {
+export function homepageFrontmatter(fm, { contentPackage, title }) {
     const slug = addressSlug(fm);
-    const data = { ...fm, package: contentPackage, title, slug, url: `${base}${slug}/` };
+    const data = { ...fm, package: contentPackage, title, slug, url: `/${slug}/` };
     delete data.aliases;
     return data;
 }

package/engine/index.mjs

@@ -92,6 +92,9 @@ export * as kbManifest from "./kb-manifest.mjs";
 /** Deriving this package's own link manifest from its content tree. */
 export * as manifestEmit from "./manifest-emit.mjs";
 
+/** Publishing the note tree as a queryable JSON Lines index. */
+export * as contentIndex from "./content-index.mjs";
+
 /** Publishing a content tree as a website: the pass, and its integrity gates. */
 export * as siteBuild from "./site-build.mjs";
 

package/engine/item-registry.mjs

@@ -188,5 +188,8 @@ export function itemArt(type, system) {
                 `note an \`img:\` of its own.`,
         );
     }
-    return resolveImg(art);
+    // `art` is non-empty by the guard above, so the translation never returns
+    // the `null` a note's unset `img:` would (#218); the coalesce states that
+    // rather than leaving the declared `string` return a half-truth.
+    return resolveImg(art) ?? "";
 }

package/engine/macros.mjs

@@ -261,7 +261,9 @@ export function buildMacroEntry(fm, { command, folder = null, stats = defaultSta
         // into chat instead of running.
         type: resolveMacroType(fm, name),
         author: null,
-        img: resolveImg(fm.img) || DEFAULT_MACRO_IMG,
+        // Nullish, not `||` (#218): a macro note that names no art gets the
+        // shared default, one that writes `img: ""` ships blank on purpose.
+        img: resolveImg(fm.img) ?? DEFAULT_MACRO_IMG,
         scope: resolveMacroScope(fm, name),
         command,
         folder,

package/engine/site-build.mjs

@@ -343,18 +343,13 @@ export function collectHomepages(contentBase, ctx) {
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
- * @param {object} [options] - Options.
- * @param {string} [options.base] - Where the package is served; defaults to the
- *   configured `site.base`, and to `/<contentPackage>/` below that.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot, pages, config, { base } = {}) {
-    const at = base || config.site?.base || `/${config.contentPackage}/`;
+export function writeHomepages(outRoot, pages, config) {
     for (const page of pages) {
         const data = homepageFrontmatter(page.fm, {
             contentPackage: config.contentPackage,
             title: homepageTitle(page.fm, config),
-            base: at,
         });
         const dest = path.join(outRoot, homepageDestination(page.fm));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -544,6 +539,16 @@ export function sectionFrontmatter(meta) {
  * package-wide address the link manifest records — the same address, one
  * segment too deep. So the address is stated and the mount does not reach it.
  *
+ * **It is stated relative to the site root, and so carries no package base**
+ * (#217). Hugo resolves a `url` against `baseURL`, whose path is already where
+ * the package is served — a consumer's Hugo site *is* its package — so writing
+ * `page.url`, which carries the base for every href this build renders, wrote
+ * that base a second time and published every content page a segment too deep
+ * (`/sohl/sohl/doc-rulesintro/`). The two are separate quantities: the page
+ * states `/<slug>/`, and everything that points *at* the page — the address
+ * index a wikilink resolves through, and the link manifest — composes
+ * `<base><slug>/`.
+ *
  * A content page carries the package the build **derived** (#65). No note
  * declares one — `package:` is retired (#56) — so the note's frontmatter alone
  * would publish a page that does not say which package it belongs to. The
@@ -571,13 +576,14 @@ export function pageFrontmatter(page, { readmeSections = {}, decorate }) {
             // Spread after the note's own frontmatter. Guarded because
             // `package: undefined` is not a value YAML can carry.
             ...(page.pkg ? { package: page.pkg } : {}),
-            // The address, stated. `slug` is written beside it because it is
-            // the last segment of that address and Hugo's own key for one; it
-            // decides nothing while `url` is present, but a page that carried
-            // only `url` would report a slug Hugo had inferred from the
-            // filename.
+            // The address, stated — site-root relative, because Hugo prefixes
+            // the site's own base to it (#217). `slug` is written beside it
+            // because it is the last segment of that address and Hugo's own key
+            // for one; it decides nothing while `url` is present, but a page
+            // that carried only `url` would report a slug Hugo had inferred
+            // from the filename.
             slug,
-            url: page.url,
+            url: `/${slug}/`,
             title: fm.title ?? name,
             kbfolder: page.folder,
         };
@@ -993,7 +999,7 @@ export function buildSite({ config, outRoot } = {}) {
             tableErrors: [],
             wikiErrors: [],
             stats: {
-                homepages: writeHomepages(homeRoot, homepages, resolved, { base }),
+                homepages: writeHomepages(homeRoot, homepages, resolved),
                 landings: 0,
                 out: homeRoot,
             },
@@ -1078,7 +1084,7 @@ export function buildSite({ config, outRoot } = {}) {
 
     // Last, and outside the mount: the package's front page is not part of the
     // content tree it introduces.
-    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved, { base });
+    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved);
 
     return {
         gates,

package/engine/system-block.mjs

@@ -52,6 +52,28 @@
  *    may be a dotted path (`data.portrait`) rather than a sibling key;
  * 4. the field's own default.
  *
+ * ## A name that collides across the two vocabularies skips step 3
+ *
+ * A field's `name` is both its identity and the shared property it draws from,
+ * and those coincide only while the two vocabularies agree about what the
+ * spelling means. They do not always. An `affiliation` item's `system.title` is
+ * the style of address an office carries — "Ajaw", "Warden"; a note's top-level
+ * `title` is the note's own heading, which the site emitter publishes. Two
+ * unrelated quantities, one spelling, and step 3 fed the first from the second.
+ *
+ * It was not a harmless coincidence either, because step 3 answers **without**
+ * applying `field.default` — only step 2 does — so an authored `title: null`
+ * reached the field's coercion unguarded and shipped as the literal string
+ * `"null"` in fifteen documents (#218).
+ *
+ * So a field may declare `topLevelMeans`: what the top-level key of that name
+ * means *instead*. Declaring it removes step 3 for that field, leaving the two
+ * positions that describe the document rather than the note. It is deliberately
+ * a per-field opt-out rather than a change to the order — step 3 is right
+ * wherever the two levels state the same quantity, which is nearly everywhere —
+ * and its value is the reason rather than a bare flag, so the collision is
+ * legible where the field is declared. See {@link module:engine/field-spec.FieldSpec}.
+ *
  * `sohlField()` — read `fm.sohl[key]`, fall back to `fm[key]` — is the
  * degenerate case where source and destination happen to share a name. It stops
  * being the general rule; {@link blockField} is what remains of it.
@@ -347,9 +369,13 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
         if (nested !== undefined) return { value: nested, from: "block" };
     }
 
-    // 3. The shared property this field declares as its source.
-    const shared = getFrontmatter(fm, field.name, undefined);
-    if (shared !== undefined) return { value: shared, from: "shared" };
+    // 3. The shared property this field declares as its source — unless the
+    //    field declares that the top-level key of that name means something
+    //    else, in which case there is no shared position to read (#218).
+    if (field.topLevelMeans === undefined) {
+        const shared = getFrontmatter(fm, field.name, undefined);
+        if (shared !== undefined) return { value: shared, from: "shared" };
+    }
 
     // 4. The field's own default.
     return { value: field.default, from: "default" };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "14.0.0",
+    "version": "16.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/actors.mjs

@@ -763,7 +763,9 @@ export class Actors extends BasePackCompiler {
             // Required nullable number: a priority, or `null` for a being that
             // is not an archetype (#126 / archetype contract #604).
             archetype: systemArchetype(fm, ctx),
-            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) || defaultImg,
+            // Nullish, not `||` (#218): a note that names no portrait gets the
+            // subtype's default, one that writes `""` ships blank on purpose.
+            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) ?? defaultImg,
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };
@@ -815,7 +817,8 @@ export class Actors extends BasePackCompiler {
         return {
             name,
             type: subType,
-            img: resolveImg(blockProperty(fm, SYSTEM, "img")) || defaultImg,
+            // Nullish, not `||` — see the portrait above (#218).
+            img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg,
             _id: id,
             system,
             items,
@@ -823,7 +826,7 @@ export class Actors extends BasePackCompiler {
                 name,
                 displayName: 0,
                 actorLink: false,
-                texture: { src: resolveImg(blockProperty(fm, SYSTEM, "img")) || defaultImg },
+                texture: { src: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg },
                 width: 1,
                 height: 1,
                 sight: { enabled: false },

package/sohl/item-fields.mjs

@@ -265,6 +265,12 @@ export const ITEM_FIELDS = Object.freeze({
             to: "title",
             ...STRING,
             default: "",
+            topLevelMeans:
+                "the note's own title — the heading its page is published under, " +
+                "which has nothing to do with the style of address an office " +
+                "carries. Author this on the membership instead: `sohl.system.title` " +
+                "on the item, or the `system.title` of the entry in a being's " +
+                "`sohl.items`.",
             describe: "The style of address the office carries.",
         },
         {

package/sohl/items.mjs

@@ -255,7 +255,10 @@ export class Items extends BasePackCompiler {
             // both registries are keyed by content type — while the document's
             // own subtype comes from the system's map (#79).
             type: subType,
-            img: resolveImg(blockProperty(fm, SYSTEM, "img")) || itemArt(type, SYSTEM),
+            // Nullish, not `||` (#218): `resolveImg` returns `null` for a note
+            // that names no art and `""` for one that wants none, and only the
+            // first may be replaced by the type's default.
+            img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? itemArt(type, SYSTEM),
             _id: id,
             system,
             effects: Array.isArray(effects) ? [...effects] : [],

package/types/content-config.d.mts

@@ -41,6 +41,7 @@ export namespace DEFAULT_PATHS {
     let content: "assets/content";
     let manifests: "assets/manifests";
     let manifestOut: "build/manifests";
+    let contentIndex: "build/content-index";
     let packJson: "build/packs-json";
     let stage: "build/stage/packs";
     let unpack: "build/tmp/packs";
@@ -296,6 +297,13 @@ export type PathsInput = {
      *       `manifests` directory.
      */
     manifestOut?: string | undefined;
+    /**
+     * Where `content-index` writes this
+     *      package's note index. Outbound, and a
+     *      derived artifact — never a source, and
+     *      never inside `stage`.
+     */
+    contentIndex?: string | undefined;
     /**
      * Build-only per-entry JSON intermediate.
      */
@@ -316,6 +324,7 @@ export type ResolvedPaths = {
     content: string;
     manifests: string;
     manifestOut: string;
+    contentIndex: string;
     packJson: string;
     stage: string;
     unpack: string;