@heroiclands/package-build 19.0.0 → 20.0.0

package/engine/frontmatter-lint.mjs

@@ -591,30 +591,93 @@ function checkTags(note, { type }) {
  * 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[]}
+ * **Each carries where it is authored**, because the two no longer agree. The
+ * specification puts an actor's portrait under `data:` and leaves its token art
+ * at the note's top level, so `portrait` has a third position to read and `img`
+ * does not — and a check that read only the two they share would pass a
+ * `data.portrait: ""` it could not see (#332).
+ *
+ * @type {readonly {key: string, inData: boolean}[]}
+ */
+const ART_FIELDS = Object.freeze([
+    Object.freeze({ key: "img", inData: false }),
+    Object.freeze({ key: "portrait", inData: true }),
+]);
+
+/**
+ * The in-block keys a type's own declarations claim for a *different* quantity.
+ *
+ * {@link module:engine/field-spec.FieldSpec.topLevelMeans} read from the other
+ * side. That property says the note's top-level key of a field's name means
+ * something else, and `resolveFieldValue` honours it by refusing to read the
+ * shared position *for that field*. The statement is symmetric: if the two
+ * positions hold unrelated quantities, then the **block** position is not the
+ * note-level field either, and a check about the note-level field must not read
+ * it.
+ *
+ * `affiliation`'s `title` is the case that named this. A note's top-level
+ * `title` is its page heading, which the site emitter publishes as
+ * `fm.title ?? name`; `sohl.title` is the style of address an office carries —
+ * "Ajaw", "Warden". Twenty-eight `sohl-kethira-basic` affiliations author
+ * `sohl.title: ""` — an office with no style of address, which is ordinary —
+ * and every one of them was reported as publishing a page with no heading. None
+ * of them does; their pages take `name.full` exactly as intended (#312).
+ *
+ * Keyed on the **in-block** key — `legacyKey` where a field declares one, and
+ * its first segment where that is dotted — because that is the position a note
+ * authors, and so the position a note-level check would otherwise read.
+ *
+ * @param {readonly object[]|null|undefined} schema - The type's declarations.
+ * @returns {Set<string>} The in-block keys that are not the note-level field of
+ *   the same name.
  */
-const ART_FIELDS = Object.freeze(["img", "portrait"]);
+function collidingBlockKeys(schema) {
+    const keys = new Set();
+    if (!Array.isArray(schema)) return keys;
+    for (const field of authoredFields(schema)) {
+        if (field.topLevelMeans === undefined) continue;
+        keys.add(String(legacyKeyOf(field)).split(".")[0]);
+    }
+    return keys;
+}
 
 /**
- * Read a shared top-level field the way the compiler reads one: the `sohl:`
- * block first, then the note's top level.
+ * Read a shared field the way the compiler reads one: the `sohl:` block first,
+ * then `data:` where the field lives there, 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).
+ * The same order {@link module:engine/system-block.resolveFieldValue} uses,
+ * restated here rather than imported so this module stays a leaf the linter can
+ * load without a resolved build configuration. Unlike that resolver 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).
+ *
+ * **`blockCollides` drops the first position**, where the note's type declares
+ * a system field of that name meaning something else — the resolver's
+ * `topLevelMeans` exemption, applied from the note-level side (#312). See
+ * {@link collidingBlockKeys}. The caller decides per key rather than this
+ * function deciding for itself, because this module knows no type's vocabulary:
+ * the declarations arrive from the caller, as `schemas` and `vocabulary` do.
  *
  * @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.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.inData=false] - Whether the field's shared source
+ *   is `data.<key>` rather than the top-level key.
+ * @param {boolean} [options.blockCollides=false] - Whether `sohl.<key>` is a
+ *   system field that merely shares this name, and so answers for nothing here.
+ * @returns {any} The authored value, or `undefined` where no position declares
+ *   one.
  */
-function authoredValue(fm, key) {
-    const block = fm?.sohl;
+function authoredValue(fm, key, { inData = false, blockCollides = false } = {}) {
+    const block = blockCollides ? undefined : fm?.sohl;
     if (block && typeof block === "object" && !Array.isArray(block) && Object.hasOwn(block, key)) {
         return block[key];
     }
+    const data = inData ? fm?.data : undefined;
+    if (data && typeof data === "object" && !Array.isArray(data) && Object.hasOwn(data, key)) {
+        return data[key];
+    }
     return fm && Object.hasOwn(fm, key) ? fm[key] : undefined;
 }
 
@@ -709,6 +772,12 @@ function checkEmbeddedShortcodes(note, blockName) {
  *   note against whatever its type declares and knows no type names of its
  *   own. Its absence skips the `data:` and `subType` checks rather than
  *   reporting every key as unknown.
+ * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a note of one type reaches its document through — the passes' own
+ *   declaration, asked through `engine/generate.mjs`'s `emittedArtFor`.
+ *   Supplied by the caller like `schemas`, so this module states no list of
+ *   iconless types of its own; absent it, an inert `img:` goes unreported
+ *   rather than every note's being (#349).
  * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
  *   The system blocks to check, and what each accepts. See
  *   {@link DEFAULT_SYSTEM_BLOCKS}.
@@ -720,13 +789,21 @@ function checkEmbeddedShortcodes(note, blockName) {
  */
 export function lintNote(
     note,
-    { schemas, index, vocabulary, packs, systems = DEFAULT_SYSTEM_BLOCKS },
+    { schemas, index, vocabulary, packs, emittedArt, systems = DEFAULT_SYSTEM_BLOCKS },
 ) {
     const findings = [];
     const fm = note.fm ?? {};
     const type = String(fm.type ?? "");
     const raw = () => note.raw ?? "";
     const at = (key, literal) => positionInFrontmatter(raw(), key, literal ?? undefined);
+    /**
+     * The in-block keys this note's own type claims for something other than
+     * the note-level field of that name, which every note-level check below
+     * reads past (#312). Resolved once: the type is fixed for the note, and
+     * each check would otherwise ask the same question of the same
+     * declarations.
+     */
+    const blockCollisions = collidingBlockKeys(schemas?.[currentType(type)]);
 
     // The retired top-level fields, checked before the type: a note may carry
     // one whatever its type is, and each finding stands on its own. Reported
@@ -797,15 +874,23 @@ export function lintNote(
     // 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.
+    // It once had a sharper reason: 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. The field declares
+    // `topLevelMeans` now, so the top-level key is no longer a source for it and
+    // `title: null` is harmless. `title: ""` is warned about on its own account
+    // below, as the *page's* heading rather than as an art path.
+    //
+    // **The collision itself did not go away, and this was where that was
+    // misread.** `topLevelMeans` settles which position the *emitted field*
+    // reads; it says nothing about which position a *check* reads, and
+    // `authoredValue` went on resolving through the block regardless — so an
+    // office with no style of address answered for its note's heading, in
+    // twenty-eight `sohl-kethira-basic` affiliations (#312). Hence
+    // `blockCollisions`: a note-level check reads past a block key its type
+    // claims for something else.
+
     // The template priority is a *shared source* — the specification states it
     // once for every type, as it does `pack` — so its retirement is reported
     // here rather than by the per-type loop below, which only reaches a field
@@ -829,8 +914,70 @@ export function lintNote(
         });
     }
 
-    for (const key of ART_FIELDS) {
-        if (authoredValue(fm, key) !== "") continue;
+    // An art field a note's own type never emits (#349). `img` is a *shared
+    // top-level* field — `BLOCK_DOCUMENT_PROPERTIES` maps it onto
+    // `document.img`, so it is legal on every note whatever the type — and a
+    // note whose document has no such property authors it, validates, compiles,
+    // and loses the value with nothing said. `Parrot` in `sohl-thalorna` had
+    // declared `img: images/mystery/parrot.webp` since long before the art rule
+    // was written and compiled `img: null`, exactly as a note declaring nothing
+    // does. The author's only evidence was the absence of an icon somewhere
+    // they were probably not looking.
+    //
+    // **Which types those are is not stated here.** It is asked of the passes,
+    // through the `emittedArt` the caller supplies — a note's type routes to a
+    // document, a document to the pass that compiles it, and the pass declares
+    // its own art. A list of iconless types kept in the linter would be a list
+    // free to drift from what is actually emitted, which is the defect rather
+    // than the check. Absent the option no claim is made, on the pattern
+    // `index` and `vocabulary` set.
+    //
+    // **Only an authored value, never `null`.** `null` is the blessed spelling
+    // for "this note names no art" (#218), and on a type with no art that is a
+    // true and harmless thing to say — it compiles identically to writing
+    // nothing. Twenty-six `sohl-thalorna` place notes are in exactly that
+    // state, and telling each of them to delete a key that already means
+    // nothing would bury the fifty-seven that name a path they believe ships.
+    //
+    // A **warning**, as the `package:` and retired-alias sweeps are: the note
+    // compiles correctly and the value is merely inert. Nor is it certainly
+    // unwanted — a note's top level is the generated page's front matter as
+    // well, so a template may read there what no document carries, which is a
+    // judgement only the tree's author can make.
+    const emitted = emittedArt ? emittedArt(currentType(type)) : null;
+    /** The art fields this note's type reaches nothing through. */
+    const inertArt = new Set(
+        emitted ? ART_FIELDS.filter(({ key }) => !emitted.art.includes(key)).map((f) => f.key) : [],
+    );
+    for (const { key, inData } of ART_FIELDS) {
+        if (!inertArt.has(key)) continue;
+        const authored = authoredValue(fm, key, {
+            inData,
+            blockCollides: blockCollisions.has(key),
+        });
+        if (typeof authored !== "string") continue;
+        findings.push({
+            file: note.file,
+            ...at(key),
+            severity: "warning",
+            message:
+                `\`${key}:\` reaches no document from a \`${type}\` note — ` +
+                (emitted?.document ?
+                    `it compiles into a ${emitted.document}, which carries no artwork`
+                :   "it compiles into a page rather than a compendium document") +
+                ", so the path is dropped. Delete the key, or move the art onto " +
+                "the note whose document is meant to show it; keep it only where " +
+                "a page template reads it as a parameter",
+        });
+    }
+
+    for (const { key, inData } of ART_FIELDS) {
+        // Reported above, and the distinction this draws does not exist there:
+        // where nothing is emitted, `""` and `null` are equally inert and the
+        // note has no default art to lose.
+        if (inertArt.has(key)) continue;
+        if (authoredValue(fm, key, { inData, blockCollides: blockCollisions.has(key) }) !== "")
+            continue;
         findings.push({
             file: note.file,
             ...at(key),
@@ -852,7 +999,13 @@ export function lintNote(
     //
     // A warning rather than an error: the value is legal under the rule, and a
     // note that genuinely wants no heading may keep it — it just has to mean it.
-    if (authoredValue(fm, "title") === "") {
+    //
+    // **The emitter reads `fm.title`, so this reads the note level.** On an
+    // `affiliation` `sohl.title` is the office's style of address, which the
+    // heading has nothing to do with — and `blockCollisions` is what keeps the
+    // two apart (#312). On every other type nothing claims the block key, so the
+    // resolution is the unchanged one.
+    if (authoredValue(fm, "title", { blockCollides: blockCollisions.has("title") }) === "") {
         findings.push({
             file: note.file,
             ...at("title"),
@@ -1198,10 +1351,15 @@ export function lintNote(
  *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
  * @param {readonly string[]} [opts.packs] - The declared pack names; see
  *   {@link lintNote}.
+ * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
+ *   What art a type reaches its document through; see {@link lintNote}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index, { schemas, vocabulary, packs, references = true, systems }) {
+export function lintFrontmatter(
+    index,
+    { schemas, vocabulary, packs, emittedArt, references = true, systems },
+) {
     const findings = [];
     const notes = [...index.notes].sort((a, b) =>
         a.file < b.file ? -1
@@ -1214,6 +1372,7 @@ export function lintFrontmatter(index, { schemas, vocabulary, packs, references
                 schemas,
                 vocabulary,
                 packs,
+                emittedArt,
                 index: references ? index : undefined,
                 ...(systems ? { systems } : {}),
             }),

package/engine/frontmatter.mjs

@@ -301,13 +301,15 @@ export function parseValueDesc(raw) {
 }
 
 /**
- * The compendium folder a note names, and how it named it.
+ * The compendium folder a note names.
  *
- * Two spellings, deliberately not merged into one value: `packFolder:` is a
- * folder note's **address** (`folder-poisonsandtoxins`) and `folder:` is a
- * Foundry **id** (`ONXsqZAIZr2qzxTb`). Which one a value is cannot be told from
- * the string — both are alphanumeric — so the field it was written in is what
- * says, and that answer is carried rather than re-derived (#251).
+ * **There is one spelling.** `packFolder:` is a folder note's **address**
+ * (`folder-poisonsandtoxins`), resolved through the address index the whole
+ * build shares. The `folder:` Foundry-id spelling this function once read
+ * beside it, and the per-pack `*-folders.yaml` that id was resolved against,
+ * are retired together (#260) — a note declaring `folder:` is refused by
+ * {@link module:engine/folder-notes.assertNoDeclaredFolder} rather than
+ * reaching here, so there is no second source for a value to come from.
  *
  * **`packFolder` was a path for one release** (`Possessions/Misc_Gear/Cooking`)
  * and is an address now (#255). A path encoded the hierarchy *in the value*, so
@@ -318,13 +320,11 @@ export function parseValueDesc(raw) {
  * authors to migrate, which is the whole reason the change was cheap enough to
  * make.
  *
- * `packFolder` wins where both are present. Nothing about `folder` changes: a
- * note that names one is read, resolved and emitted exactly as before, until
- * #260 retires it.
- *
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @returns {{value: string|null, isAddress: boolean}} The authored value, and
- *   whether it is a folder note's address.
+ *   whether it is a folder note's address. `isAddress` is always `true` and is
+ *   kept so a caller reads the same shape it always did; it distinguished the
+ *   two spellings, and there is only one left to be.
  */
 export function folderField(fm) {
     const asAddress = sohlField(fm, "packFolder", null);

package/engine/generate.mjs

@@ -23,10 +23,12 @@
  * Each `*` compiler walks the whole content tree and selects its own entries by
  * the note's `type` — every note in the tree belongs to this repository's
  * `contentPackage` (#56) — so routing is directory-agnostic: a file lands in a
- * pack because of its `type`, not its location. Which packs exist and which
- * folder hierarchy each one loads are declared in
- * `package-build.config.yaml`; folder files live under the content root and are
- * referenced from entry frontmatter via `sohl.folder: <id>`.
+ * pack because of its `type`, not its location. Which packs exist is declared
+ * in `package-build.config.yaml`; the **folder hierarchy is not declared
+ * anywhere**. A folder is a note like any other (#256), named by `packFolder`
+ * — its address — and it materialises in every pack that holds a document
+ * naming it, its ancestors with it (#257). So no pack loads a folder list, and
+ * two packs can no longer disagree about a folder they both hold.
  *
  * **The order the passes run in is derived, not declared** — see
  * {@link orderPassesByDependency}. The declared list is the manifest's `packs`
@@ -66,7 +68,10 @@ import { buildCompileCorpus } from "./compile-corpus.mjs";
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { routerFor } from "./pack-router.mjs";
-import { unclaimedNoteFindings } from "./note-claims.mjs";
+import { NEVER_PACKED_TYPES, unclaimedNoteFindings } from "./note-claims.mjs";
+// Which document a content type compiles into, so the art declaration below is
+// answered from the same routing the compile uses (#349).
+import { RETIRED_TYPES, currentType, packForType } from "./ids.mjs";
 import { contentPackage } from "./content-package.mjs";
 
 /**
@@ -131,6 +136,56 @@ export function compilerFor(docType, system = null) {
     return (system && SYSTEM_COMPILERS[system]?.[docType]) || COMPILERS[docType];
 }
 
+/**
+ * The art fields a note of one content type reaches its document through, and
+ * the document it reaches (#349).
+ *
+ * **Derived, never listed.** A note's type routes to a document type
+ * ({@link packForType}), a document type routes to the pass that compiles it
+ * ({@link compilerFor}), and the pass declares which art it emits
+ * ({@link BasePackCompiler.emitsArt}). So the answer is assembled from the same
+ * three statements the compile itself follows, and a pass that starts or stops
+ * emitting art changes this by changing its own declaration. A second table of
+ * "types with no image" would be a table free to drift from what is emitted,
+ * which is the defect this exists to report rather than to reproduce.
+ *
+ * **The union across systems**, because a note is compiled by whichever pack
+ * claims it: a tree feeding both SoHL and HM3 has two Actor passes, and a field
+ * either of them emits is live for the note. Only a field *no* pass emits is
+ * inert, and that is the finding this supports.
+ *
+ * @param {string} type - The note's content type.
+ * @returns {{document: string|null, art: readonly string[]}|null} What the type
+ *   compiles into and the art it carries there, or `null` where no claim can be
+ *   made — a retired type, which is reported as retired instead.
+ */
+export function emittedArtFor(type) {
+    const name = String(type ?? "");
+    if (!name || Object.hasOwn(RETIRED_TYPES, name)) return null;
+
+    // A homepage compiles into a *page*, not a compendium document, so nothing
+    // it authors reaches one. It is the one type whose absence from every pack
+    // is the intended state (`NEVER_PACKED_TYPES`).
+    if (NEVER_PACKED_TYPES.has(currentType(name))) return { document: null, art: [] };
+
+    // A folder reaches a pack by a route of its own — it materialises in every
+    // pack holding a document that references it — so `packForType` has no
+    // answer for it and no compiler class writes it. `folderDocument` does, and
+    // a Foundry `Folder` has no artwork at all.
+    if (currentType(name) === FOLDER_TYPE) return { document: "Folder", art: [] };
+
+    const { docType } = packForType(name);
+    const passes = [
+        COMPILERS[docType],
+        ...Object.values(SYSTEM_COMPILERS).map((bySystem) => bySystem[docType]),
+    ].filter(Boolean);
+    if (!passes.length) return null;
+
+    const art = new Set();
+    for (const pass of passes) for (const field of pass.emitsArt ?? []) art.add(field);
+    return { document: docType, art: Object.freeze([...art]) };
+}
+
 /**
  * Root of the build-only JSON tree for one pack.
  *
@@ -656,11 +711,13 @@ export async function generatePacksJson({ only, config = loadPackConfig() } = {}
                 // which wins over the id it derives under the folder namespace.
                 // A record's `id` is not that: the index fills it in for every
                 // addressable note (#270), so handing records straight over
-                // would make every folder look pinned and file each one under a
-                // different id than the packs address it by. The index cannot
-                // tell a pin from a derivation, so the note is read — and only
-                // folder notes are, 79 of `sohl`'s 1,685 rather than all of
-                // them.
+                // would make every folder look pinned. Since #310 the *value*
+                // would be right either way — the index derives a folder's id
+                // under the folder namespace, so the two agree — but `derivedId`
+                // would not, and it is what tells an author whether a duplicate
+                // id was two pins or two addresses. The index cannot tell a pin
+                // from a derivation, so the note is read — and only folder notes
+                // are, 79 of `sohl`'s 1,685 rather than all of them.
                 corpus.records
                     .filter(
                         (record) =>

package/engine/helpers.mjs

@@ -400,15 +400,92 @@ export function makeFilename(name, id) {
  * non-alphanumerics collapsed to single hyphens.
  */
 
+/**
+ * The path prefixes that name a package other than the one being compiled.
+ *
+ * Foundry serves every installed package from a root named for its kind, so a
+ * path opening with one of these is already a served address and belongs to
+ * somebody else — most often `systems/sohl/assets/…`, where every default this
+ * toolchain ships lives, and which a module's content cites as readily as the
+ * system's own does.
+ *
+ * **Two, not "the ones we happen to use".** `worlds/` is left out on purpose: a
+ * package may not ship art out of a world, so a note that writes one has made a
+ * mistake, and prefixing it yields a plainly broken path rather than a
+ * plausible one that fails silently much later.
+ *
+ * @type {readonly string[]}
+ */
+const FOREIGN_PACKAGE_ROOTS = Object.freeze(["systems/", "modules/"]);
+
+/**
+ * Whether a path already addresses something this package does not own, and so
+ * must be emitted exactly as authored.
+ *
+ * Three shapes qualify, each a different kind of "not mine":
+ *
+ * - **Another package** — `systems/…` or `modules/…`, per
+ *   {@link FOREIGN_PACKAGE_ROOTS}.
+ * - **Somewhere off this install** — a URI scheme (`https:`, `data:`) or a
+ *   protocol-relative `//cdn…`.
+ * - **The data root itself** — a leading `/`, which Foundry serves from the
+ *   install rather than from any package.
+ *
+ * @param {string} s - A non-empty authored path.
+ * @returns {boolean} Whether it passes through untranslated.
+ */
+function addressesAnotherPackage(s) {
+    if (FOREIGN_PACKAGE_ROOTS.some((root) => s.startsWith(root))) return true;
+    // `//host/x.png` — protocol-relative, so it leaves this origin entirely.
+    // Checked before the single-slash case, which would otherwise claim it.
+    if (s.startsWith("//")) return true;
+    // `/x.png` — rooted at the Foundry data root, not at any package.
+    if (s.startsWith("/")) return true;
+    // `https://…`, `data:…`, `file:…` — a scheme, so not a path at all.
+    return /^[a-z][a-z0-9+.-]*:/i.test(s);
+}
+
 /**
  * Translate a content-relative image path into its Foundry-relative form.
  *
  * Content frontmatter (`img` / `portrait`) authors a single path that has to
- * work for Foundry, the knowledgebase, and the website. For Foundry the bundled
- * 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.
+ * work for Foundry, the knowledgebase, and the website. **Its first segment
+ * says which package owns the file** (#331), and there are exactly three
+ * answers:
+ *
+ * | Authored path starts with | Owner                 | Emitted              |
+ * | ------------------------- | --------------------- | -------------------- |
+ * | `systems/`                | a separate **system** | unchanged            |
+ * | `modules/`                | a separate **module** | unchanged            |
+ * | anything else             | **this package**      | `<assetRoot>/<path>` |
+ *
+ * So `icons/relic.svg` compiles to `systems/sohl/assets/icons/relic.svg` here
+ * and to `modules/sohl-thalorna/assets/icons/relic.svg` in a module — the asset
+ * root is derived from the configuration, and is the one place `systems/sohl`
+ * is ever spelled (#1508). An authored
+ * `systems/sohl/assets/icons/noun/shield.svg` is left exactly as written,
+ * whichever package is compiling it.
+ *
+ * **This is a rule about ownership, not an allowlist of directories.** It used
+ * to prefix `icons/…` and `images/…` and pass everything else through — the
+ * same answer for every path any tree authors today, and the wrong one for the
+ * next directory a package ships. `sohl-kethira-basic` keeps art under
+ * `assets/artwork/`, so an authored `artwork/deity.webp` would have shipped
+ * unprefixed: a 404 in Foundry, reported by nothing. That a package owns its
+ * own tree is the fact; the directory names inside it are that package's
+ * business (#331).
+ *
+ * **Off-install addresses pass through too**, which is the same rule rather
+ * than a fourth: a URL, a `data:` URI, or a `/`-rooted path names something no
+ * package owns. See {@link addressesAnotherPackage}.
+ *
+ * **`banner:` does not follow this rule, deliberately (#331).** It is not an
+ * asset path inside a Foundry install at all: it reaches no compiled document,
+ * and its only consumer is the Hugo theme, which prefixes a relative value with
+ * `images/` and joins it onto `params.cdnBaseURL`. The two fields look alike
+ * and address different places — `img:` a file Foundry serves, `banner:` a file
+ * the CDN serves — so they are documented apart rather than reconciled into one
+ * rule that would be true of neither.
  *
  * **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
@@ -453,10 +530,10 @@ export function resolveImg(raw, config = loadPackConfig()) {
     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}`;
-    }
-    return s;
+    // Somebody else's to serve — emit it exactly as authored.
+    if (addressesAnotherPackage(s)) return s;
+    // Ours, so root it where Foundry serves this package's files from.
+    return `${config.assetRoot}/${s}`;
 }
 
 /**

package/engine/index.mjs

@@ -69,6 +69,9 @@ export * as notePackage from "./note-package.mjs";
 /** Frontmatter fields a note may no longer declare, and the refusal of them. */
 export * as retiredFields from "./retired-fields.mjs";
 
+/** Schema fields a note may never declare, because play writes them. */
+export * as runtimeOnlyFields from "./runtime-only-fields.mjs";
+
 /** The package homepage: the note type that compiles to a page, not a document. */
 export * as homepage from "./homepage.mjs";
 

package/engine/item-compiler.mjs

@@ -66,6 +66,9 @@ import { documentSubtype, subtypeRow } from "./document-subtypes.mjs";
 // `system` verbatim, and `<system>.img` / `.effects` / `.flags` overriding
 // their shared top-level forms for this system alone (#58).
 import { blockField, blockProperty, claimedPaths, mergeSystemData } from "./system-block.mjs";
+// The other direction of the same declaration: a field the *document* writes in
+// play, which a note may not author and the builder does not emit (#330).
+import { assertNoRuntimeOnlyFields } from "./runtime-only-fields.mjs";
 
 /**
  * The description an item carries: a pointer to its **item doc**, the
@@ -113,6 +116,17 @@ export class SystemItemCompiler extends BasePackCompiler {
      */
     static requiresSystemBlock = true;
 
+    /**
+     * An Item carries an `img` — its icon — which this pass writes from the
+     * note's own path, falling back to the type's default art.
+     *
+     * `portrait` is **not** among them: a portrait is a being's sheet picture,
+     * and an item has nowhere to put one.
+     *
+     * @type {readonly string[]}
+     */
+    static emitsArt = Object.freeze(["img"]);
+
     /**
      * The note-type → document-subtype map this pass compiles against.
      *
@@ -174,6 +188,29 @@ export class SystemItemCompiler extends BasePackCompiler {
         return !row || row.document === "Item";
     }
 
+    /**
+     * Refuse a note authoring one of its type's **runtime-only** fields (#330).
+     *
+     * A schema declares fields the document writes for itself — an affliction's
+     * `onsetDate` is the world time its onset fired at — and a note authoring
+     * one used to compile, because `<system>.system` is a verbatim passthrough
+     * and the field really is in the schema. The result was shipped content
+     * carrying one world's play state, with the build reporting success.
+     *
+     * The declaration says which, so nothing here knows a field name; see
+     * {@link module:engine/runtime-only-fields}.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {void}
+     * @throws {Error} When the note authors one.
+     */
+    assertAuthorable(fm) {
+        assertNoRuntimeOnlyFields(fm, itemFields(fm.type, this.system), {
+            block: this.system,
+            absPath: this.currentNote?.absPath,
+        });
+    }
+
     /**
      * The Foundry Item subtype a note compiles into.
      *