@heroiclands/package-build 22.11.0 → 22.12.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @heroiclands/package-build
 
+## 22.12.1
+
+### Patch Changes
+
+**Content authoring**
+
+- Image embeds and Markdown images accept named size hints, so notes can carry the intended size while their displayed appearance stays the same.
+
+## 22.12.0
+
+### Minor Changes
+
+- **References:** An Address in note data that names no local or declared dependency target now reports an error; missing artwork keeps its fallback warning.
+
 ## 22.11.0
 
 ### Minor Changes

package/CONTENT.md

@@ -1249,6 +1249,12 @@ somewhere other than where they were made, or not at all:
   reference answered by a vendored manifest lands exactly as it would in a
   wikilink. `--no-references` turns this one off for a tree whose cross-package
   references it cannot see.
+- **Dead Address reference** — an Address-valued `data:` field naming no local
+  note, asset or entry in a declared dependency index. The finding names the
+  field and the complete Address it names. A short form means this package;
+  another package requires the full Address. `--no-references` also turns off
+  this target check. Art slots report unresolved art through their own fallback
+  warning.
 
 **A schema says what a note may _write_, not what the compiler emits.** Those
 are different, and the difference is the whole calibration of the check: a note

package/docs/api.md

@@ -935,16 +935,17 @@ Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cann
 
 ### `engine.contentImages`
 
-An image saying how wide it is and where it sits. A markdown image carries no indication of either, so each of the three surfaces decides for itself and the author — who is the one who knows — has no way to say. A directive in the curly-attribute convention Pandoc and Kramdown use closes that, in two closed vocabularies: a width class, and a `float:` position.
+An image saying how wide it is and where it sits. A markdown image carries no indication of either, so each of the three surfaces decides for itself and the author — who is the one who knows — has no way to say. A directive in the curly-attribute convention Pandoc and Kramdown use closes that, in three closed vocabularies: a width class, a named `size:`, and a `float:` position. The named size is accepted without affecting display.
 
 | Export                | Signature                                       | Returns                                                                                                                                        | Use it when                                                                  |
 | --------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                              | The width classes an image may carry, and what each means to a renderer.     |
+| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                              | The named sizes an image directive accepts without applying a display size.  |
 | `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                              | The `float:` positions an image may take, and where each puts it.            |
 | `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                              | The class every figure carries, whatever its width or position.              |
 | `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                              | A markdown image, with the directive it may carry.                           |
 | `imageSourceProblem`  | `function imageSourceProblem(src)`              | {string} The problem, as a finding's sentence, or `""`.                                                                                        | What is wrong with an image's address, or `""` when nothing is.              |
-| `parseImageDirective` | `function parseImageDirective(raw)`             | {{classes: string[], float: string, problems: string[]}} What was written, and what cannot be honoured.                                        | Read the directive on an image.                                              |
+| `parseImageDirective` | `function parseImageDirective(raw)`             | {{classes: string[], size: string, float: string, problems: string[]}} What was written, and what cannot be honoured.                          | Read the directive on an image.                                              |
 | `figureClasses`       | `function figureClasses(directive)`             | {string} A space-separated class list.                                                                                                         | The classes a figure carries, from a parsed directive.                       |
 | `escapeHtml`          | `function escapeHtml(text)`                     | {string} The same value, safe in markup.                                                                                                       | Text going inside an HTML attribute or between tags.                         |
 | `imageFigureHtml`     | `function imageFigureHtml(image)`               | {string} The figure, as one HTML block.                                                                                                        | One image as the `<figure>` both HTML surfaces render.                       |

package/docs/content-format.md

@@ -1315,6 +1315,12 @@ Address-keyed relation maps hold typed targets and standing values. Only generat
 output serializes these properties to Address strings. Runtime Shortcodes,
 Foundry UUIDs, file paths and URLs keep their own representations.
 
+An Address-valued `data:` field must name a target in this package or a declared
+dependency index. `content-build lint` reports a missing target as an error at
+the value or map key that names it. A stub counts as a target for data even
+though it publishes no page. Art slots use their own missing-art warning and
+document fallback.
+
 #### An omitted segment defaults from where the link is written
 
 It is **not** a wildcard and resolution is not a search. Every short form expands
@@ -1854,15 +1860,16 @@ immediately after the closing `]]`, with no space:
 
 ```markdown
 ![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
+![[branwldrgr|Brànwâal Dôrgaar]]{size: medium, float: top-left}
 ![[thalornamap|Map of Thalorna]]{.full-width}
 ![[thalornamap|Map of Thalorna]]{.full-width, float: top-left}
 ![[thalornamap|Map of Thalorna]]{float: top-left, .full-width}
 ```
 
-**The same parser reads both**, so an embed takes a width class, a `float:`, or
-both together in either order, comma-separated — everything
+**The same parser reads both**, so an embed takes a width class, a `size:`, a
+`float:`, or a combination in any order, comma-separated — everything
 [an image's directive](#width-is-a-class-and-the-ordinary-width-carries-no-marker)
-takes and nothing beyond it. The width and position vocabularies are the ones
+takes and nothing beyond it. The width, size, and position vocabularies are the ones
 above, and they are closed here for the same reason: a directive that is quietly
 ignored looks exactly like one that worked, and a directive holding a problem is
 not honoured in part either.
@@ -2117,6 +2124,7 @@ part of this format follows.
 
 ```markdown
 ![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
+![[branwldrgr|Brànwâal Dôrgaar]]{size: medium, float: top-left}
 
 ![Map of Thalorna](images/maps/thalorna.webp){.full-width}
 ```
@@ -2140,13 +2148,30 @@ place for those words and this is it.
 | `.full-width` | the full page | full content width | full page width  |
 
 The simple case needs no spelling, which is why the ordinary width has no name.
-A third width joins this table as a name.
 
 **No pixel values, ever.** A number means something in a browser and nothing
 coherent in print, and a directive carrying a class and a dimension at once
 gives one question two answers with no rule for which wins. `{width=800}` is
 refused.
 
+##### Named size is `size:`
+
+| `size` value | display                  |
+| ------------ | ------------------------ |
+| `auto`       | same as omitting `size:` |
+| `small`      | same as omitting `size:` |
+| `medium`     | same as omitting `size:` |
+| `large`      | same as omitting `size:` |
+| `xlarge`     | same as omitting `size:` |
+| `full-width` | same as omitting `size:` |
+
+The parser accepts and records these names for Markdown images and embedded
+assets. **A `size:` value does not change the displayed dimensions** on the
+website, in Foundry, or in the book. With no `size:`, the parser records `auto`;
+the existing rendering rules apply. In particular, book images occupy a column
+unless they carry `.full-width`. A `size:` may sit before or after `float:` in
+the same directive, and neither changes the other's behavior.
+
 ##### Position is `float:`
 
 | `float` value  | book                 | website and Foundry journal     |
@@ -2176,7 +2201,7 @@ A `.full-width` image that **also states a `float:`** is asking for a float and
 gets one, with no break before it. A float is placed where it fits, which may be
 the next page.
 
-##### Both vocabularies are closed
+##### All three vocabularies are closed
 
 `{.fullwidth}`, `{.full_width}`, `{width=800}` and `{float: middle}` are
 refused, located by file, line and column, and the build fails. An unrecognised
@@ -2188,8 +2213,8 @@ even in the part that parsed: a half-honoured directive is the same silent
 failure in a smaller costume. The image keeps its braces and renders them as
 literal text, so the mistake is visible on the page as well as in the log.
 
-**Nothing else reaches emitted markup.** The two vocabularies and the address
-are all that leave a note; there is no `style`, no `id` and no arbitrary
+**Nothing else reaches emitted markup.** The width and position classes and the
+address are all that leave a note; there is no `style`, no `id` and no arbitrary
 attribute, because data is never compiled into markup here. An address carries
 a scheme of `http:` or `https:`, or none at all.
 
@@ -3015,9 +3040,7 @@ If `sohl` is present, this becomes an `affliction` item.
 | `subType`                          | `system.subType`                     | NA    |
 | `data.transmission`                | `system.transmission`                | NA    |
 | `data.outcome`                     | `system.outcome`                     | NA    |
-| `data.healingRate`                 | `system.healingRateBase`             | NA    |
 | `data.contagionIndex`              | `system.contagionIndexBase`          | NA    |
-| `data.outcomeTraumas`              | `system.outcomeTraumas`              | NA    |
 | `data.onsetDurationFormula`        | `system.onsetDurationFormula`        | NA    |
 | `data.onsetDurationBase`           | `system.onsetDurationBase`           | NA    |
 | `data.healingCheckDurationFormula` | `system.healingCheckDurationFormula` | NA    |
@@ -3055,6 +3078,10 @@ that writes one fails the build. They are world times, and `0` is a valid one,
 so there is no blank a note could write either; leave them out and the data
 model's `null` stands.
 
+`data.healingRate` and `data.outcomeTraumas` are page data. SoHL reads an
+affliction’s base healing rate from `sohl.healingRateBase`. Its item declaration
+does not read `data.outcomeTraumas`.
+
 ### type: armorgear
 
 Note: `data.quantity` may not be specified. Quantity is always 1.
@@ -3129,7 +3156,9 @@ if a `sohl` property is present, a SoHL item of type "concoctiongear" will be cr
 | `data.value`      | `system.valueBase`      | NA    |
 | `data.quality`    | `system.qualityBase`    | NA    |
 | `data.durability` | `system.durabilityBase` | NA    |
-| `data.quantity`   | `system.quantity`       | NA    |
+
+`data.quantity` is page data for a concoction. SoHL sets `system.quantity` to
+`1` for each compendium item.
 
 ### type: containergear
 
@@ -3142,19 +3171,21 @@ Note: `data.quantity` may not be specified; quantity is always set to 1.
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `capacity`         | `number` | Container capacity (in lbs)                |
+| `capacity`         | `number` | HM3 container capacity (in lbs)            |
 
 if a `sohl` property is present, a SoHL item of type "containergear" will be created.
 
 if a `hm3` property is present, an HM3 item of type "containergear" will be created.
 
-| shared source     | → sohl                   | → hm3                 |
-| ----------------- | ------------------------ | --------------------- |
-| `data.weight`     | `system.weightBase`      | `system.weight`       |
-| `data.value`      | `system.valueBase`       | `system.value`        |
-| `data.quality`    | `system.qualityBase`     | NA                    |
-| `data.durability` | `system.durabilityBase`  | NA                    |
-| `data.capacity`   | `system.maxCapacityBase` | `system.capacity.max` |
+| shared source     | → sohl                  | → hm3                 |
+| ----------------- | ----------------------- | --------------------- |
+| `data.weight`     | `system.weightBase`     | `system.weight`       |
+| `data.value`      | `system.valueBase`      | `system.value`        |
+| `data.quality`    | `system.qualityBase`    | NA                    |
+| `data.durability` | `system.durabilityBase` | NA                    |
+| `data.capacity`   | NA                      | `system.capacity.max` |
+
+SoHL reads a container’s capacity in pounds from `sohl.maxCapacity`.
 
 ### type: miscgear
 
@@ -3165,7 +3196,7 @@ if a `hm3` property is present, an HM3 item of type "containergear" will be crea
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `quantity`         | `number` | Gear quantity (default: 1)                 |
+| `quantity`         | `number` | HM3 gear quantity (default: 1)             |
 
 if a `sohl` property is present, a SoHL item of type "miscgear" will be created.
 
@@ -3177,7 +3208,9 @@ if a `hm3` property is present, an HM3 item of type "miscgear" will be created.
 | `data.value`      | `system.valueBase`      | `system.value`    |
 | `data.quality`    | `system.qualityBase`    | NA                |
 | `data.durability` | `system.durabilityBase` | NA                |
-| `data.quantity`   | `system.quantity`       | `system.quantity` |
+| `data.quantity`   | NA                      | `system.quantity` |
+
+SoHL sets `system.quantity` to `1` for each compendium item.
 
 ### type: mystery
 
@@ -3213,10 +3246,12 @@ if a `sohl` property is present, a SoHL item of type "mystery" will be created.
 | --------------------- | ----------------------- | ----- |
 | `subType`             | `system.subType`        | NA    |
 | `data.skillAptitudes` | `system.skillAptitudes` | NA    |
-| `data.level`          | `system.levelBase`      | NA    |
 | `data.charges.value`  | `system.charges.value`  | NA    |
 | `data.charges.max`    | `system.charges.max`    | NA    |
 
+`data.level` is page data for a mystery. SoHL reads the item’s level from
+`sohl.levelBase`.
+
 ### type: mysticalability
 
 **subType**:
@@ -3250,13 +3285,15 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 `sohl.system` as shortcodes and have no shared source; `data.assocSkill` and
 `data.assocAffiliation` name the same two notes as Addresses, for the page.
 
-| shared source        | → sohl                    | → hm3         |
-| -------------------- | ------------------------- | ------------- |
-| `subType`            | `system.subType`          | **see above** |
-| `data.masteryLevel`  | `system.masteryLevelBase` | NA            |
-| `data.level`         | `system.levelBase`        | NA            |
-| `data.charges.value` | `system.charges.value`    | NA            |
-| `data.charges.max`   | `system.charges.max`      | NA            |
+| shared source        | → sohl                 | → hm3         |
+| -------------------- | ---------------------- | ------------- |
+| `subType`            | `system.subType`       | **see above** |
+| `data.charges.value` | `system.charges.value` | NA            |
+| `data.charges.max`   | `system.charges.max`   | NA            |
+
+`data.masteryLevel` and `data.level` are page data for an ability. SoHL reads
+the item’s base mastery and level from `sohl.masteryLevelBase` and
+`sohl.levelBase`.
 
 ### type: projectilegear
 
@@ -3276,7 +3313,7 @@ If an `hm3` property is present, an HM3 item is created, and `hm3.type` states w
 | `value`            | `number` | Gear value                                 |
 | `quality`          | `number` | Gear quality                               |
 | `durability`       | `number` | Gear durability                            |
-| `quantity`         | `number` | Gear quantity (default: 1)                 |
+| `quantity`         | `number` | HM3 gear quantity (default: 1)             |
 
 if a `sohl` property is present, a SoHL item of type "projectilegear" will be created.
 
@@ -3293,7 +3330,9 @@ HM3 side while remaining distinct on the SoHL side.
 | `data.value`      | `system.valueBase`      | `system.value`    |
 | `data.quality`    | `system.qualityBase`    | NA                |
 | `data.durability` | `system.durabilityBase` | NA                |
-| `data.quantity`   | `system.quantity`       | `system.quantity` |
+| `data.quantity`   | NA                      | `system.quantity` |
+
+SoHL sets `system.quantity` to `1` for each compendium item.
 
 ### type: skill
 
@@ -3313,7 +3352,7 @@ HM3 side while remaining distinct on the SoHL side.
 | `data` property    | Values    | Description                                |
 | ------------------ | --------- | ------------------------------------------ |
 | `templatePriority` | `number`  | Template priority, _null_ = not a template |
-| `masteryLevel`     | `number`  | Mastery Level                              |
+| `masteryLevel`     | `number`  | HM3 mastery level                          |
 | `parentSkill`      | `Address` | Parent skill this skill specializes        |
 
 if a `sohl` property is present, a SoHL item of type "skill" will be created.
@@ -3326,10 +3365,12 @@ Note: `hm3.system.type` (skill types) use the values "Craft", "Physical", "Commu
 skill this one specializes, and has no shared source; `data.parentSkill` names that
 skill as an Address, for the page.
 
-| shared source       | → sohl                    | → hm3                 |
-| ------------------- | ------------------------- | --------------------- |
-| `subType`           | `system.subType`          | See notes above       |
-| `data.masteryLevel` | `system.masteryLevelBase` | `system.masteryLevel` |
+| shared source       | → sohl           | → hm3                 |
+| ------------------- | ---------------- | --------------------- |
+| `subType`           | `system.subType` | See notes above       |
+| `data.masteryLevel` | NA               | `system.masteryLevel` |
+
+SoHL reads a skill’s base mastery from `sohl.masteryLevelBase`.
 
 ### type: trauma
 

package/docs/getting-started.md

@@ -332,6 +332,18 @@ an error. A `data:` block and a `sohl:` / `hm3:` block are closed: a misspelled
 key there is a finding that names the key you meant.
 [`content-format.md`](content-format.md) is the specification.
 
+An image stands in its own paragraph. Its directive accepts a named size and a
+position together:
+
+```markdown
+![[icon-anubis|Anubis]]{size: medium, float: top-left}
+```
+
+The accepted sizes are `auto`, `small`, `medium`, `large`, `xlarge`, and
+`full-width`. Omitting `size:` means `auto`. The build checks the name, but
+`size:` does not change the displayed dimensions on the website, in Foundry, or
+in the book. See [Images](content-format.md#images) for the rendering rules.
+
 ## Step 6 — check the tree
 
 Four checks, and they are quick enough to run continuously while authoring.

package/engine/content-images.mjs

@@ -19,14 +19,15 @@
  *     ![Brànwâal Dôrgaar](images/beings/branwldrgr-portrait.webp){float: top-left}
  *     ![Map of Thalorna](images/map.webp){.full-width}
  *
- * ## Two closed vocabularies, and closed is the point
+ * ## Three closed vocabularies, and closed is the point
  *
  * **Width is a class**, and the ordinary width carries no marker at all — the
  * simple case needs no spelling. {@link IMAGE_CLASSES} holds the one class
  * there is. **Position is `float:`**, and {@link IMAGE_FLOATS} holds the five
- * values it takes.
+ * values it takes. **Named size is `size:`**, and {@link IMAGE_SIZES} holds its
+ * values. Size is parsed but does not change the figure's current presentation.
  *
- * Both are closed, and an unrecognised value is **refused with a located
+ * All three are closed, and an unrecognised value is **refused with a located
  * diagnostic** rather than ignored. Ignoring is the failure worth preventing:
  * `{.fullwidth}` rendering as an ordinary image looks exactly like a directive
  * that worked, so the author publishes a page that is not the one they asked
@@ -36,8 +37,7 @@
  *
  * **No pixel values.** A number means something in a browser and nothing
  * coherent in print, and a directive carrying both a class and a dimension
- * gives one question two answers with no rule for which wins. A third width
- * joins the vocabulary as a name.
+ * gives one question two answers with no rule for which wins.
  *
  * **Not `markdown-it-attrs`.** It is a general attribute injector: it will set
  * `style`, `id` or `onclick`, and those reach emitted markup on the website and
@@ -105,6 +105,16 @@ export const IMAGE_CLASSES = Object.freeze({
     },
 });
 
+/** The named sizes an image directive accepts without applying a display size. */
+export const IMAGE_SIZES = Object.freeze([
+    "auto",
+    "small",
+    "medium",
+    "large",
+    "xlarge",
+    "full-width",
+]);
+
 /**
  * The `float:` positions an image may take, and where each puts it.
  *
@@ -213,16 +223,18 @@ export function imageSourceProblem(src) {
  *
  * Values are validated here rather than at the point of rendering, so a mistake
  * is one finding with a position rather than three surfaces quietly drawing
- * something else. A directive that holds a problem yields **no** class and no
+ * something else. A directive that holds a problem yields **no** class, size or
  * float: a half-honoured directive is the silent failure in a smaller costume.
  *
  * @param {string} [raw] - The text between the braces, braces included or not.
- * @returns {{classes: string[], float: string, problems: string[]}} What was
+ * @returns {{classes: string[], size: string, float: string, problems: string[]}} What was
  *   written, and what cannot be honoured.
  */
 export function parseImageDirective(raw) {
     /** @type {string[]} */
     const classes = [];
+    let size = "auto";
+    let sizeSeen = false;
     let float = "";
     /** @type {string[]} */
     const problems = [];
@@ -230,7 +242,7 @@ export function parseImageDirective(raw) {
     const inner = String(raw ?? "")
         .replace(/^\{/, "")
         .replace(/\}$/, "");
-    if (!inner.trim()) return { classes, float, problems };
+    if (!inner.trim()) return { classes, size, float, problems };
 
     // Split on commas, not whitespace: `float: top-left` is one pair with a
     // space in it, and the space after the colon is the spelling people write.
@@ -259,17 +271,32 @@ export function parseImageDirective(raw) {
         const colon = part.indexOf(":");
         if (colon === -1) {
             problems.push(
-                `\`${part}\` is neither a width class nor \`float: <position>\` — an ` +
-                    "image states its width as a class and its position as `float:`, " +
+                `\`${part}\` is neither a width class nor \`size: <name>\` or ` +
+                    "`float: <position>` — an image states its width as a class and its position as `float:`, " +
                     "and it states no dimensions at all",
             );
             continue;
         }
         const key = part.slice(0, colon).trim();
         const value = part.slice(colon + 1).trim();
+        if (key === "size") {
+            if (!IMAGE_SIZES.includes(value)) {
+                problems.push(
+                    `\`size: ${value}\` is not a size — the ones there are: ${IMAGE_SIZES.join(", ")}`,
+                );
+                continue;
+            }
+            if (sizeSeen) {
+                problems.push("`size:` is written twice, and an image has one named size");
+                continue;
+            }
+            size = value;
+            sizeSeen = true;
+            continue;
+        }
         if (key !== "float") {
             problems.push(
-                `\`${key}\` is not an image attribute — \`float\` is the only one, ` +
+                `\`${key}\` is not an image attribute — use \`size\` or \`float\`, ` +
                     "and width is a class rather than an attribute",
             );
             continue;
@@ -292,8 +319,8 @@ export function parseImageDirective(raw) {
         problems.push("an image states one width, and this states more than one");
     }
     // Nothing partial: a directive with a problem in it is not honoured at all.
-    if (problems.length) return { classes: [], float: "", problems };
-    return { classes, float, problems };
+    if (problems.length) return { classes: [], size: "auto", float: "", problems };
+    return { classes, size, float, problems };
 }
 
 /**
@@ -594,7 +621,7 @@ export function lintContentImages(contentBase, { skipDirectories = [], config }
  * **Hugo is handed markdown, not a rendered page.** The site emitter writes a
  * note's body through verbatim, so a `{…}` directive left in it reaches the
  * page as its own literal braces: Goldmark's block-attribute parser is off, and
- * turning it on would accept `style` and `id` alongside the two vocabularies,
+ * turning it on would accept `style` and `id` alongside the closed vocabularies,
  * which is the injection surface this rule exists to avoid. So the directive is
  * resolved here, into markup Goldmark passes through.
  *

package/engine/frontmatter-lint.mjs

@@ -68,7 +68,7 @@ import { positionInFrontmatter, positionOfFrontmatterPath } from "./diagnostics.
 import { pathnameProblem } from "./pathnames.mjs";
 import { checkHomepageAddressFields } from "./homepage.mjs";
 import { RETIRED_TYPES, RENAMED_TYPES, currentType, renamedTypeMessage } from "./ids.mjs";
-import { parseAddress, acceptsType } from "./address.mjs";
+import { parseAddress, acceptsType, renderAddress } from "./address.mjs";
 import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
 import { isAddressSegment } from "./address-charset.mjs";
 // The one place the "every pack not named" key is spelled. Imported rather
@@ -421,7 +421,7 @@ function dataBlock(fm) {
  *   was loaded to recognise it would be worse than not checking.
  * @returns {object[]} Findings.
  */
-function checkDataContainer(note, { type, fields, packs, addressContext }) {
+function checkDataContainer(note, { type, fields, packs, addressContext, index }) {
     const findings = [];
     const { present, entries, malformed } = dataBlock(note.fm ?? {});
     if (!present) return findings;
@@ -504,7 +504,7 @@ function checkDataContainer(note, { type, fields, packs, addressContext }) {
             });
             continue;
         }
-        findings.push(...checkDataReferences(note, field, value, segments, addressContext));
+        findings.push(...checkDataReferences(note, field, value, segments, addressContext, index));
         // A `scalar-or-map` written in its map form is checked entry by entry,
         // because that is the correction an author has to make: one key's
         // value, not the whole map. Quoting the map back would name every
@@ -521,15 +521,16 @@ function checkDataContainer(note, { type, fields, packs, addressContext }) {
 }
 
 /**
- * Validate typed entries without resolving their targets.
+ * Validate typed entries and resolve declared non-art Address targets.
  * @param {object} note - The authored note.
  * @param {object} field - Its data field declaration.
  * @param {unknown} value - The field value.
  * @param {string[]} segments - The field's path under `data`.
  * @param {object} context - The builder's Address context.
+ * @param {object} [index] - The local and declared dependency Address index.
  * @returns {object[]} Located findings.
  */
-function checkDataReferences(note, field, value, segments, context) {
+function checkDataReferences(note, field, value, segments, context, index) {
     const checks = [];
     if (field.kind === "address") checks.push({ value, path: [], kind: "address" });
     if (field.entryKind) {
@@ -573,10 +574,16 @@ function checkDataReferences(note, field, value, segments, context) {
         let reason;
         if (!matchesKind(check.value, check.kind, defaults))
             reason = `should be ${check.kind === "address" ? "an Address" : "a Shortcode"}`;
-        else if (check.kind === "address" && accepted) {
+        else if (check.kind === "address") {
             const tuple = parseAddress(check.value, defaults, { declared: true });
-            if (!acceptsType(tuple, accepted))
+            if (accepted && !acceptsType(tuple, accepted))
                 reason = `accepts ${accepted.join(" or ")}, not ${tuple.type}`;
+            else if (
+                index?.addressHit &&
+                !ART_SLOTS.some((slot) => slot.key === field.name) &&
+                !index.addressHit(renderAddress(tuple))
+            )
+                reason = `names ${renderAddress(tuple)}, which does not resolve in this package or its declared dependencies`;
         }
         if (!reason) continue;
         const path = ["data", ...segments, ...check.path];
@@ -1519,6 +1526,7 @@ export function lintNote(
                 fields,
                 packs,
                 addressContext: referenceContext,
+                index,
             }),
         );
         findings.push(...checkSubType(note, { type, entry }));

package/engine/holdings.mjs

@@ -124,15 +124,12 @@ export const HELD_SUBTYPES = Object.freeze(["settlement", "site", "structure"]);
  * system, only the shortcode {@link module:engine/address} would resolve it
  * to anyway.
  *
- * **The match this shortcode feeds is deliberately package-blind.** `places`
- * and `affiliations` merge this package's own notes with every fetched
- * dependency's into one shortcode space, first declaration wins — the way a
- * dependency's generic geography attaches to whatever a consumer calls the
- * same shortcode, which is the point of _A dependency's places and
- * affiliations take part_ above. Comparing the full Address instead would
- * ask an entry's package to agree with the citing note's, and a fetched
- * entry's own `parents` or `domains` is written in *its* package while the
- * blend it takes part in is *this* one's — see
+ * **The holdings graph has package-blind Shortcode identity.** `places` and
+ * `affiliations` merge local and fetched notes into one shortcode space; the
+ * first declaration wins. A fetched place attaches to a local parent with
+ * the same shortcode, and a fetched affiliation can name both local and
+ * fetched domains. The authored entries remain Addresses; this graph uses
+ * their shortcode projection for containment and tenure. See
  * `tests/site-holdings.test.ts`'s `empire.domains: ["mill", "abroad"]`, where
  * `mill` is local and `abroad` is the dependency's own, both bare, both
  * correct only because neither package is asked.
@@ -321,6 +318,7 @@ export function holdingsPages(nodes) {
         // Read through the one reader, so a caller handing in what a note
         // wrote — an address, a wikilink, a repeat — is read as `holdingsNode`
         // reads it.
+        // Shortcode identity: the first node of each type owns this graph key.
         by.set(shortcode, {
             ...node,
             shortcode,

package/engine/map-places.mjs

@@ -108,15 +108,14 @@ const PLACE_TYPES = Object.freeze(new Set(["place"]));
  * since this position asks neither its package nor its system, only the
  * shortcode {@link module:engine/address} would resolve it to anyway.
  *
- * **The match this shortcode feeds is deliberately package-blind.**
- * `world.places` merges this package's own places with every fetched
- * dependency's into one shortcode space, the way a dependency's place
- * attaches to the local containment tree it is drawn beside — see
+ * **The map graph has package-blind Shortcode identity.** `world.places`
+ * merges local and fetched places by shortcode, with local declarations
+ * taking precedence. A fetched place attaches to the local containment tree
+ * by its parent's shortcode. The authored parent remains an Address; the map
+ * uses its shortcode projection for containment, layout, and DOT nodes. See
  * `tests/map.test.ts`'s _loads a dependency's places beside the package's
  * own_, where a fetched place's bare `parents: ["world"]` reaches this
- * package's own root. Comparing the full Address instead would ask the
- * dependency's own package to agree with this one's, which the feature is
- * built to cross.
+ * package's own root.
  *
  * @param {unknown} parent - One `parents` entry.
  * @returns {string} Its shortcode, or `""` for an entry that names nothing.
@@ -193,6 +192,7 @@ export function placesFromRecords(records, { contentBase, base }) {
             // lint's finding.
             if (places.has(shortcode)) continue;
             const data = record.data && typeof record.data === "object" ? record.data : {};
+            // Shortcode identity: local places claim the map node first.
             places.set(shortcode, {
                 shortcode,
                 name,
@@ -243,6 +243,7 @@ function addForeignPlaces(world, foreignIndex) {
         if (entry?.type !== "place") continue;
         const shortcode = readCanonicalKey(canonical)?.shortcode?.toLowerCase() ?? "";
         if (!shortcode || world.places.has(shortcode)) continue;
+        // Shortcode identity: fetched places fill only unclaimed map nodes.
         world.places.set(shortcode, {
             shortcode,
             name: String(entry.name ?? shortcode),

package/engine/populations.mjs

@@ -242,8 +242,10 @@ export function foreignNode(canonical, entry) {
 /**
  * The corpus a link index describes.
  *
- * A shortcode is declared once per type and the first declaration wins, so a
- * local note shadows a dependency's the way the link resolver answers.
+ * Population containment and tenure use the same package-blind Shortcode
+ * identity as holdings and maps. Each type has one node per shortcode, with
+ * local notes taking precedence over fetched entries. A fetched place can
+ * attach to local geography, while its authored `parents` remains an Address.
  *
  * @param {object} index - The link index.
  * @returns {Corpus} The corpus.
@@ -263,6 +265,7 @@ function corpusOf(index) {
         if (!node) return;
         const by = node.type === "place" ? places : affiliations;
         if (by.has(node.shortcode)) return;
+        // Shortcode identity: the first node of each type owns this graph key.
         by.set(node.shortcode, 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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.11.0",
+    "version": "22.12.1",
     "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/types/engine/content-images.d.mts

@@ -16,15 +16,16 @@ export function imageSourceProblem(src: string): string;
  *
  * Values are validated here rather than at the point of rendering, so a mistake
  * is one finding with a position rather than three surfaces quietly drawing
- * something else. A directive that holds a problem yields **no** class and no
+ * something else. A directive that holds a problem yields **no** class, size or
  * float: a half-honoured directive is the silent failure in a smaller costume.
  *
  * @param {string} [raw] - The text between the braces, braces included or not.
- * @returns {{classes: string[], float: string, problems: string[]}} What was
+ * @returns {{classes: string[], size: string, float: string, problems: string[]}} What was
  *   written, and what cannot be honoured.
  */
 export function parseImageDirective(raw?: string): {
     classes: string[];
+    size: string;
     float: string;
     problems: string[];
 };
@@ -182,7 +183,7 @@ export function lintContentImages(contentBase: string, { skipDirectories, config
  * **Hugo is handed markdown, not a rendered page.** The site emitter writes a
  * note's body through verbatim, so a `{…}` directive left in it reaches the
  * page as its own literal braces: Goldmark's block-attribute parser is off, and
- * turning it on would accept `style` and `id` alongside the two vocabularies,
+ * turning it on would accept `style` and `id` alongside the closed vocabularies,
  * which is the injection surface this rule exists to avoid. So the directive is
  * resolved here, into markup Goldmark passes through.
  *
@@ -248,6 +249,8 @@ export const IMAGE_CLASSES: Readonly<Record<string, {
     scope: string;
     describe: string;
 }>>;
+/** The named sizes an image directive accepts without applying a display size. */
+export const IMAGE_SIZES: readonly string[];
 /**
  * The `float:` positions an image may take, and where each puts it.
  *