@heroiclands/package-build 22.9.2 → 22.10.0

package/engine/pdf-toc.mjs

@@ -48,6 +48,7 @@
  * @module
  */
 
+import { encodeAddresses } from "./address-values.mjs";
 import { slugify } from "./content-slug.mjs";
 import { positionOfYamlPath } from "./diagnostics.mjs";
 
@@ -464,8 +465,18 @@ export function planDocument(nodes, { selections = new Map() } = {}) {
             sections: entries.filter((e) => e.kind === "section").length,
             prose: entries.filter((e) => e.kind === "prose").length,
             notes: entries.filter((e) => e.kind === "note").length,
-            distinct: links.size,
-            repeated: selected - links.size,
+            distinct: new Set(
+                entries
+                    .filter((e) => e.kind === "note")
+                    .map((e) => e.record.address?.slug ?? e.record.shortcode),
+            ).size,
+            repeated:
+                selected -
+                new Set(
+                    entries
+                        .filter((e) => e.kind === "note")
+                        .map((e) => e.record.address?.slug ?? e.record.shortcode),
+                ).size,
             skipped: nodes.length - entries.filter((e) => e.kind === "section").length,
         },
     };
@@ -521,6 +532,10 @@ function emitSection(node, nodes, ctx) {
             // First occurrence wins the address: however many times the book
             // prints an entry, `[[weapongear-dagger]]` reaches one page.
             if (!ctx.links.has(slug)) ctx.links.set(slug, anchor);
+            for (const address of [record?.address?.canonical, record?.documentation]) {
+                if (address && !ctx.links.has(encodeAddresses(address)))
+                    ctx.links.set(encodeAddresses(address), anchor);
+            }
             ctx.entries.push({
                 kind: "note",
                 record,

package/engine/place-relations.mjs

@@ -18,11 +18,21 @@
  * two structural relations are stated here: `data.borders`, the places it
  * shares a frontier with, and `data.routes`, the journeys from its centre to
  * another place. Both are lists of entries naming the other place by
- * shortcode, and both are stated **from each end**: A at `NE` of B is the same
+ * **Address**, and both are stated **from each end**: A at `NE` of B is the same
  * fact as B at `SW` of A, so a note stating one side of it and a neighbour
  * stating a different side is a contradiction the lint reports rather than a
  * discovery made while writing a third note.
  *
+ * **`to` is an Address, written at whatever length says what it means.** Its
+ * `<type>` segment defaults to `place` and `place` is the whole of its accepted
+ * set, so `vylar`, `place-vylar` and `thalorna-none-place-vylar` name one place
+ * and a `to` naming anything else is an error. The `<package>` segment defaults
+ * to **the package doing the building** — wherever the value was written, and
+ * whether it was authored here or carried back by a fetched index — so a short
+ * `to` always names a place in the package being built, naming a dependency's
+ * place is what the fully qualified form is for, and two places sharing a
+ * shortcode in different packages never answer for each other.
+ *
  * **The value sets are closed and stated once.** The eight bearings, the three
  * travel modes, the days markers and the terrain registry are the constants
  * below, read by the lint, compared against the specification's tables by the
@@ -45,17 +55,36 @@
  * through the same resolver a wikilink does and a dependency's places take
  * part: a fetched index entry carries the relation the record stated, and a
  * border across a package boundary is checked from both ends like any other.
+ * Across that boundary the far side states the frontier in the fully qualified
+ * form, which is the only form that names this package's place from over there —
+ * a short `to` in a dependency's record names the package being built, so the
+ * long form is not optional for a cross-package border.
  *
  * @module
  */
 
+import { encodeAddresses } from "./address-values.mjs";
+
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
-import { isAddressSegment } from "./address-charset.mjs";
+import { acceptsType, parseAddress, renderAddress } from "./address.mjs";
+import { NO_SYSTEM } from "./document-subtypes.mjs";
 
 /* --------------------------------------------------------------------- */
 /*  The closed sets                                                       */
 /* --------------------------------------------------------------------- */
 
+/**
+ * The type a border's or a route's `to` names.
+ *
+ * It is both the default its `<type>` segment takes when an author omits it and
+ * the whole of the set the position accepts, which is what makes `vylar` and
+ * `place-vylar` the same Address and a `to` naming a `lore` note an error rather
+ * than a lookup that quietly finds nothing.
+ *
+ * @type {string}
+ */
+export const RELATION_TYPE = "place";
+
 /**
  * The eight compass bearings, clockwise from north.
  *
@@ -160,7 +189,7 @@ export function oppositeBearing(bearing) {
  * directly, copied from the record when the index was loaded.
  *
  * @param {object} hit - What the index resolved.
- * @returns {{type: string, borders: unknown, routes: unknown, parents: unknown, name: string}}
+ * @returns {{type: string, borders: unknown, routes: unknown, parents: unknown}}
  *   The relation it states.
  */
 function relationsOf(hit) {
@@ -171,7 +200,6 @@ function relationsOf(hit) {
             borders: data.borders,
             routes: data.routes,
             parents: data.parents,
-            name: String(hit.fm.shortcode ?? ""),
         };
     }
     return {
@@ -179,53 +207,84 @@ function relationsOf(hit) {
         borders: hit?.borders,
         routes: hit?.routes,
         parents: hit?.parents,
-        name: "",
     };
 }
 
 /**
- * The shortcode a `parents` entry names.
+ * The Address defaults a place's relation values are read against.
+ *
+ * The vocabularies are the tree's, so every position reads one grammar, and
+ * there is **one** set of defaults: the package is always the one being built.
+ * That is the whole of the cross-package rule, and it holds for both ends of a
+ * frontier — a note's own relations and the relations a fetched index carries
+ * back are read the same way, so a short value in a dependency's record names a
+ * place in the package being built and a dependency names a place of its own by
+ * writing the Address in full. `place` is the type an omitted `<type>` segment
+ * takes, and a place is a core document, so the system is `none`.
+ *
+ * @param {object} [index] - The link index, for the tree's vocabularies and the
+ *   package being built.
+ * @returns {object} The defaults {@link parseAddress} takes.
+ */
+function addressDefaults(index) {
+    return {
+        types: index?.types ?? new Set([RELATION_TYPE]),
+        packages: index?.packages,
+        noIndexPackages: index?.noIndexPackages,
+        package: index?.contentPackage,
+        system: NO_SYSTEM,
+        type: RELATION_TYPE,
+    };
+}
+
+/**
+ * The canonical Address a written relation value names, or `undefined` where it
+ * names no place.
  *
- * A parent is written as a bare shortcode, and may be written as an address;
- * a shortcode is the last segment either way, because a segment carries no
- * separator.
+ * Every comparison between two ends of a relation goes through this, so the two
+ * are compared as the Addresses they name rather than as the strings two authors
+ * happened to type.
  *
- * @param {unknown} parent - One `parents` entry.
- * @returns {string} Its shortcode.
+ * @param {unknown} written - The value as authored.
+ * @param {object} defaults - What {@link addressDefaults} returns.
+ * @returns {string|undefined} The canonical `package-none-place-shortcode`.
  */
-function parentShortcode(parent) {
-    return String(parent ?? "")
-        .split("-")
-        .pop()
-        .toLowerCase();
+function placeAddress(written, defaults) {
+    if (!defaults.package) return undefined;
+    const read = parseAddress(written, defaults);
+    if (read.reason || !acceptsType(read, [RELATION_TYPE])) return undefined;
+    return renderAddress(read);
 }
 
 /**
  * Whether one place's `parents` names another.
  *
  * @param {unknown} parents - The `parents` list.
- * @param {string} shortcode - The place asked about.
+ * @param {string|undefined} address - The place asked about, as its Address.
+ * @param {object} defaults - What {@link addressDefaults} returns.
  * @returns {boolean} Whether it is named.
  */
-function hasParent(parents, shortcode) {
-    return Array.isArray(parents) && parents.some((p) => parentShortcode(p) === shortcode);
+function hasParent(parents, address, defaults) {
+    if (!address || !Array.isArray(parents)) return false;
+    return parents.some((p) => placeAddress(p, defaults) === address);
 }
 
 /**
  * The entries of a relation list that name one place.
  *
  * @param {unknown} list - A `borders` or `routes` value.
- * @param {string} shortcode - The place they name.
+ * @param {string|undefined} address - The place they name, as its Address.
+ * @param {object} defaults - What {@link addressDefaults} returns.
  * @returns {Record<string, unknown>[]} The entries.
  */
-function entriesTo(list, shortcode) {
-    if (!Array.isArray(list)) return [];
+function entriesTo(list, address, defaults) {
+    if (!address || !Array.isArray(list)) return [];
     return list.filter(
         (e) =>
             e &&
             typeof e === "object" &&
             !Array.isArray(e) &&
-            String(e.to ?? "").toLowerCase() === shortcode,
+            placeAddress(e.to, defaults) === address,
     );
 }
 
@@ -289,6 +348,19 @@ function checkRelation(note, { field, index }) {
 
     const raw = note.raw ?? "";
     const self = String(fm.shortcode ?? "").toLowerCase();
+    // One set of defaults, read by both ends: an omitted `<package>` segment is
+    // always the package being built.
+    const here = addressDefaults(index);
+    /** This place, as the Address the far end has to name it by. */
+    const selfAddress =
+        here.package && self ?
+            renderAddress({
+                package: here.package,
+                system: NO_SYSTEM,
+                type: RELATION_TYPE,
+                shortcode: self,
+            })
+        :   undefined;
     const isRoute = field === "routes";
     const keys = isRoute ? ROUTE_KEYS : BORDER_KEYS;
     const at = (i, key) =>
@@ -327,21 +399,46 @@ function checkRelation(note, { field, index }) {
             );
         }
 
-        // `to`: a shortcode, and one a place declares.
+        // `to`: an Address naming a place, and one a place declares.
         const to = entry.to;
         let target;
         let toIsValid = false;
+        /** The one canonical Address `to` names, once it parses. */
+        let toAddress;
+        const read = parseAddress(to, here);
         if (to === undefined || to === null || to === "") {
             error(i, undefined, `${label(i)} must name the other place in \`to\``);
-        } else if (typeof to !== "string" || !isAddressSegment(to)) {
+        } else if (
+            read.reason === "no-content-index" ||
+            (!read.reason && here.noIndexPackages?.has(read.package))
+        ) {
+            error(
+                i,
+                "to",
+                `${label(i, "to")} names package "${read.package}", which is declared ` +
+                    `\`contentIndex: false\` — a Foundry dependency only, with no content ` +
+                    `index fetched for it, so nothing it publishes can be named here`,
+            );
+        } else if (read.reason) {
+            error(
+                i,
+                "to",
+                `${label(i, "to")} must name a place — the other place's \`shortcode\`, or ` +
+                    `its address as \`${RELATION_TYPE}-<shortcode>\` or ` +
+                    `\`<package>-${NO_SYSTEM}-${RELATION_TYPE}-<shortcode>\` for a place in ` +
+                    `another package — but reads ${JSON.stringify(encodeAddresses(to))}`,
+            );
+        } else if (!acceptsType(read, [RELATION_TYPE])) {
             error(
                 i,
                 "to",
-                `${label(i, "to")} must be a shortcode — the other place's ` +
-                    `\`shortcode\`, not an address — but reads ${JSON.stringify(to)}`,
+                `${label(i, "to")} names a \`${read.type}\`, and a ` +
+                    `${isRoute ? "route" : "border"} is between places, so it names a ` +
+                    `\`${RELATION_TYPE}\` — but reads ${JSON.stringify(encodeAddresses(to))}`,
             );
         } else if (index) {
-            const hit = index.referenceHit(`place-${to}`);
+            toAddress = renderAddress(read);
+            const hit = index.addressHit(toAddress);
             if (hit) {
                 target = relationsOf(hit);
                 toIsValid = true;
@@ -350,14 +447,18 @@ function checkRelation(note, { field, index }) {
                 // slip, and naming it says what was found rather than only
                 // what was not.
                 const other = (index.notes ?? []).find(
-                    (n) => String(n.fm?.shortcode ?? "").toLowerCase() === to.toLowerCase(),
+                    (n) =>
+                        String(n.fm?.shortcode ?? "").toLowerCase() === read.shortcode &&
+                        String(n.type ?? "") !== RELATION_TYPE,
                 );
                 error(
                     i,
                     "to",
-                    `${label(i, "to")} names "${to}", and no place in this package or a ` +
-                        `fetched index declares that shortcode` +
-                        (other ? `; the ${other.type} note "${to}" is not a place` : ""),
+                    `${label(i, "to")} names "${encodeAddresses(to)}", and no place at ${toAddress} is ` +
+                        `declared by this package or by a fetched index` +
+                        (other ?
+                            `; the ${other.type} note "${read.shortcode}" is not a place`
+                        :   ""),
                 );
             }
         } else {
@@ -463,7 +564,11 @@ function checkRelation(note, { field, index }) {
         }
 
         if (!toIsValid) return;
-        const toKey = String(to).toLowerCase();
+        // The pair is keyed on the Address rather than on the written form, so
+        // one place named once bare and once qualified is the one pair it is.
+        // With no index there is no package to complete the Address with, and
+        // the shortcode is all the note itself states.
+        const toKey = toAddress ?? read.shortcode;
 
         // Once per pair — per mode, on a route.
         const modes = seen.get(toKey) ?? new Set();
@@ -473,9 +578,9 @@ function checkRelation(note, { field, index }) {
                 i,
                 undefined,
                 isRoute ?
-                    `${label(i)} lists "${to}" by ${mode} twice; a pair appears in \`routes\` ` +
+                    `${label(i)} lists "${encodeAddresses(to)}" by ${mode} twice; a pair appears in \`routes\` ` +
                         `once per mode`
-                :   `${label(i)} lists "${to}" twice; a pair appears in \`borders\` once`,
+                :   `${label(i)} lists "${encodeAddresses(to)}" twice; a pair appears in \`borders\` once`,
             );
             return;
         }
@@ -488,7 +593,7 @@ function checkRelation(note, { field, index }) {
             error(
                 i,
                 "to",
-                `${label(i, "to")} names "${to}", which is a ${target.type} note; a ` +
+                `${label(i, "to")} names "${encodeAddresses(to)}", which is a ${target.type} note; a ` +
                     `${field === "borders" ? "border" : "route"} is between places`,
             );
             return;
@@ -497,20 +602,20 @@ function checkRelation(note, { field, index }) {
         // Containment is `parents`; a border to a parent or a child restates
         // it as adjacency, and the two cannot both be true.
         if (!isRoute) {
-            if (hasParent(data.parents, toKey)) {
+            if (hasParent(data.parents, toAddress, here)) {
                 error(
                     i,
                     undefined,
-                    `${label(i)} borders "${to}", which is this place's parent; ` +
+                    `${label(i)} borders "${encodeAddresses(to)}", which is this place's parent; ` +
                         `containment is \`parents\`, and a place never borders its parent`,
                 );
                 return;
             }
-            if (hasParent(target.parents, self)) {
+            if (hasParent(target.parents, selfAddress, here)) {
                 error(
                     i,
                     undefined,
-                    `${label(i)} borders "${to}", which is this place's child; ` +
+                    `${label(i)} borders "${encodeAddresses(to)}", which is this place's child; ` +
                         `containment is \`parents\`, and a place never borders its child`,
                 );
                 return;
@@ -518,8 +623,13 @@ function checkRelation(note, { field, index }) {
         }
 
         if (!bearingIsValid) return;
-        const back = entriesTo(target[field], self);
+        const back = entriesTo(target[field], selfAddress, here);
         const expected = oppositeBearing(bearing);
+        // How the far end writes this place: its bare `shortcode` within the same
+        // package, and the full Address across a package boundary, where the far
+        // note is authored in a package whose own short forms name its own
+        // places.
+        const selfThere = read.package === here.package || !selfAddress ? self : selfAddress;
 
         if (!isRoute) {
             if (back.length === 0) {
@@ -528,9 +638,9 @@ function checkRelation(note, { field, index }) {
                         i,
                         undefined,
                         "warning",
-                        `"${self}" borders "${to}" at ${bearing}, but "${to}" states no ` +
+                        `"${self}" borders "${encodeAddresses(to)}" at ${bearing}, but "${encodeAddresses(to)}" states no ` +
                             `border to "${self}"; it should carry ` +
-                            `\`{ to: ${self}, bearing: ${expected} }\``,
+                            `\`{ to: ${selfThere}, bearing: ${expected} }\``,
                     ),
                 );
                 return;
@@ -540,7 +650,7 @@ function checkRelation(note, { field, index }) {
                 error(
                     i,
                     "bearing",
-                    `"${self}" borders "${to}" at ${bearing}, so "${to}" should state the ` +
+                    `"${self}" borders "${encodeAddresses(to)}" at ${bearing}, so "${encodeAddresses(to)}" should state the ` +
                         `border back at bearing ${expected}, but states ${theirs}`,
                 );
             }
@@ -554,9 +664,9 @@ function checkRelation(note, { field, index }) {
                     i,
                     undefined,
                     "warning",
-                    `"${self}" reaches "${to}" by ${mode} in ${days} days, but "${to}" ` +
+                    `"${self}" reaches "${encodeAddresses(to)}" by ${mode} in ${days} days, but "${encodeAddresses(to)}" ` +
                         `states no route to "${self}"; it should carry ` +
-                        `\`{ to: ${self}, bearing: ${expected}, mode: ${mode}, days: ${days} }\``,
+                        `\`{ to: ${selfThere}, bearing: ${expected}, mode: ${mode}, days: ${days} }\``,
                 ),
             );
             return;
@@ -573,7 +683,7 @@ function checkRelation(note, { field, index }) {
             error(
                 i,
                 "mode",
-                `"${self}" reaches "${to}" by ${mode}, but "${to}" states the route back ` +
+                `"${self}" reaches "${encodeAddresses(to)}" by ${mode}, but "${encodeAddresses(to)}" states the route back ` +
                     `by ${oneOf(theirs)} only; a pair is stated by the same mode at ` +
                     `both ends`,
             );
@@ -584,7 +694,7 @@ function checkRelation(note, { field, index }) {
             error(
                 i,
                 "bearing",
-                `"${self}" reaches "${to}" at ${bearing}, so "${to}" should state the route ` +
+                `"${self}" reaches "${encodeAddresses(to)}" at ${bearing}, so "${encodeAddresses(to)}" should state the route ` +
                     `back at bearing ${expected}, but states ${theirBearing}`,
             );
         }
@@ -593,7 +703,7 @@ function checkRelation(note, { field, index }) {
             error(
                 i,
                 "days",
-                `"${self}" reaches "${to}" by ${mode} in ${days} days, but "${to}" states ` +
+                `"${self}" reaches "${encodeAddresses(to)}" by ${mode} in ${days} days, but "${encodeAddresses(to)}" states ` +
                     `the route back as ${theirDays}; both ends state the same days`,
             );
         }
@@ -605,7 +715,7 @@ function checkRelation(note, { field, index }) {
 /**
  * Check a place note's `data.borders`.
  *
- * Every `to` is a shortcode a place declares, every `bearing` is one of the
+ * Every `to` is an Address a place declares, every `bearing` is one of the
  * eight, no pair is listed twice, no target is the note's own parent or child,
  * and the other end states the pair back at the opposite bearing — a missing
  * reciprocal is a warning naming both notes, a wrong one an error.

package/engine/populations.mjs

@@ -54,6 +54,7 @@
  */
 
 import { positionOfFrontmatterPath, positionOfLiteral } from "./diagnostics.mjs";
+import { readCanonicalKey } from "./content-address.mjs";
 import { shortcodesOf } from "./holdings.mjs";
 
 /**
@@ -145,8 +146,12 @@ const CORPUS = new WeakMap();
  *                                                whose `parents` name it.
  * @property {Map<string, string[]>} holdersOf    Place shortcode → the polities
  *                                                whose `domains` name it.
- * @property {Map<string, PopulationNode>} byAddress `type-shortcode` → the node,
- *                                                for the citation rule.
+ * @property {Map<string, PopulationNode>} byAddress `type/shortcode` → the
+ *                                                node, for the citation rule.
+ *                                                Package-blind by design: a
+ *                                                local note shadows a
+ *                                                dependency's, so this is
+ *                                                never a canonical Address.
  */
 
 /**
@@ -219,10 +224,10 @@ function localNode(note) {
  * @param {object} entry - The entry.
  * @returns {PopulationNode|null} The node.
  */
-function foreignNode(canonical, entry) {
+export function foreignNode(canonical, entry) {
     const type = String(entry?.type ?? "");
     if (type !== "place" && type !== "affiliation") return null;
-    const shortcode = canonical.split("-").pop()?.toLowerCase() ?? "";
+    const shortcode = readCanonicalKey(canonical)?.shortcode?.toLowerCase() ?? "";
     if (!shortcode) return null;
     return {
         shortcode,
@@ -259,8 +264,11 @@ function corpusOf(index) {
         const by = node.type === "place" ? places : affiliations;
         if (by.has(node.shortcode)) return;
         by.set(node.shortcode, node);
-        const address = `${node.type}-${node.shortcode}`;
-        if (!byAddress.has(address)) byAddress.set(address, node);
+        // Not a canonical Address: package-blind by design, so a local place
+        // shadows a foreign one of the same type and shortcode. `/` keeps that
+        // distinct from the `-`-joined form every canonical Address renders.
+        const key = `${node.type}/${node.shortcode}`;
+        if (!byAddress.has(key)) byAddress.set(key, node);
     };
 
     for (const note of index.notes ?? []) take(localNode(note));
@@ -499,7 +507,7 @@ export function checkPopulation(note, { index } = {}) {
  * @type {RegExp}
  */
 const CITED =
-    /\[\[((?:place|affiliation)-[a-z0-9.]+)(?:\\?\|[^\]]*)?\]\]([^[\n]{0,80}?)~([0-9](?:[0-9,]*[0-9])?)(?![\w%]|[.,]\d|[-–—])/g;
+    /\[\[(place|affiliation)-([a-z0-9.]+)(?:\\?\|[^\]]*)?\]\]([^[\n]{0,80}?)~([0-9](?:[0-9,]*[0-9])?)(?![\w%]|[.,]\d|[-–—])/g;
 
 /**
  * Check the populations a `doc` note cites against the notes they belong to.
@@ -531,8 +539,8 @@ export function checkCitedPopulations(note, { index } = {}) {
 
     CITED.lastIndex = 0;
     for (const match of body.matchAll(CITED)) {
-        const [, address, , figure] = match;
-        const target = corpus.byAddress.get(address.toLowerCase());
+        const [, type, shortcode, , figure] = match;
+        const target = corpus.byAddress.get(`${type}/${shortcode}`.toLowerCase());
         if (!target || target.population === undefined) continue;
         const claimed = Number(figure.replace(/,/g, ""));
         if (!Number.isFinite(claimed) || claimed === target.population) continue;

package/engine/reference-targets.mjs

@@ -0,0 +1,54 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { completeAddress, renderAddress } from "./address.mjs";
+import { systemOf } from "./document-subtypes.mjs";
+import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+
+/**
+ * Names and published destinations for reference presentation.
+ * Stubs contribute names, never pages or documents. The published index
+ * remains separate so body-link validation retains its publication rules.
+ * @param {readonly object[]} records - Decoded local or fetched records.
+ * @param {Map<string, object>} [published] - Actual published link destinations.
+ * @returns {Map<string, object>} Canonical lookup keys and presentation values.
+ */
+export function buildReferenceTargets(records, published = new Map()) {
+    const targets = new Map();
+    for (const record of records) {
+        if (!record.package || !record.type || !record.shortcode) continue;
+        const value = { name: record.name?.full ?? record.name, subType: record.subType };
+        for (const system of new Set([
+            systemOf(record.type, KNOWN_DOCUMENT_SUBTYPE_MAPS),
+            "none",
+        ])) {
+            const address = completeAddress({
+                package: record.package,
+                system,
+                type: record.type,
+                shortcode: record.shortcode,
+            });
+            const key = renderAddress(address);
+            targets.set(key, { ...targets.get(key), ...value });
+        }
+        for (const [system, entry] of Object.entries(record.foundry ?? {})) {
+            const address = completeAddress({
+                package: record.package,
+                system,
+                type: record.type,
+                shortcode: record.shortcode,
+            });
+            const key = renderAddress(address);
+            targets.set(key, {
+                ...targets.get(key),
+                ...value,
+                ...(entry.uuid ? { uuid: entry.uuid } : {}),
+            });
+        }
+    }
+    for (const [key, value] of published) targets.set(key, { ...targets.get(key), ...value });
+    return targets;
+}

package/engine/scenes.mjs

@@ -427,8 +427,11 @@ export class Scenes extends BasePackCompiler {
         const scene = buildScene(fm, {
             packageId: foundryPackageId(),
             // The art resolver, so the map pass turns an address into the path
-            // each surface serves without holding an index of its own.
-            art: (value, key, type) => this.artPathOf(value, key, type),
+            // each surface serves without holding an index of its own. `accepts`
+            // is threaded through so `bgImage`, one of the four declared art
+            // slots, is held to its own accepted set here exactly as it is
+            // through `artPath`.
+            art: (value, key, type, accepts) => this.artPathOf(value, key, type, accepts),
             name,
             folder,
             stats: this.stats,

package/engine/shortcode-references.mjs

@@ -0,0 +1,68 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { completeAddress, isAddressTuple, readCanonicalKey, renderAddress } from "./address.mjs";
+
+const nativeIndexes = new WeakMap();
+
+/**
+ * Index a completed presentation map by native namespace and Shortcode.
+ * Callers finish populating a map before resolving references through it.
+ * @param {Map<string, object>} index - Completed identity index.
+ * @returns {Map<string, object[]>} Native matches grouped by declared namespace.
+ */
+function nativeIndex(index) {
+    if (nativeIndexes.has(index)) return nativeIndexes.get(index);
+    const grouped = new Map();
+    for (const [key, value] of index) {
+        const address = readCanonicalKey(key);
+        if (!isAddressTuple(address)) continue;
+        const namespace = `${address.system}/${address.type}/${address.shortcode}`;
+        const matches = grouped.get(namespace) ?? [];
+        matches.push({ key, address, value });
+        grouped.set(namespace, matches);
+    }
+    nativeIndexes.set(index, grouped);
+    return grouped;
+}
+
+/**
+ * Present a native Shortcode using its unique system/type target.
+ * Address properties never use this lookup. Multiple packages claiming the
+ * same native identity remain ambiguous. Documentation supplies links; the
+ * native target supplies a name even when its documentation is unpublished.
+ * @param {readonly Map<string, object>[]} indexes - Published identity indexes.
+ * @param {unknown} code - Native Shortcode.
+ * @param {{type: string, system: string}} hint - Its declared native namespace.
+ * @returns {object|undefined} Documentation presentation, or no unique target.
+ */
+export function resolveShortcodeReference(indexes, code, hint) {
+    if (typeof code !== "string" || !code || !hint.type || !hint.system) return undefined;
+    const matches = new Map();
+    const namespace = `${hint.system}/${hint.type}/${code.toLowerCase()}`;
+    for (const index of indexes) {
+        if (!index) continue;
+        for (const match of nativeIndex(index).get(namespace) ?? [])
+            if (!matches.has(match.key)) matches.set(match.key, match);
+    }
+    if (matches.size !== 1) return undefined;
+    const { address: native, value } = matches.values().next().value;
+    const address = completeAddress({
+        package: native.package,
+        system: "none",
+        type: native.type,
+        shortcode: native.shortcode,
+    });
+    const key = renderAddress(address);
+    const documentation = indexes.map((index) => index?.get(key)).find(Boolean);
+    return {
+        name: documentation?.name ?? value.name,
+        subType: documentation?.subType ?? value.subType,
+        address,
+        ...(documentation?.uuid ? { uuid: documentation.uuid } : {}),
+        ...(documentation?.url ? { url: documentation.url } : {}),
+    };
+}