@heroiclands/package-build 23.4.1 → 23.5.0

package/engine/pathnames.mjs

@@ -36,15 +36,23 @@
  * being built, and the whole of it is the suffix. That is the ordinary case and
  * the one nearly every note writes.
  *
- * The four forms, for a `harnensemble` note writing `images/map.webp`
+ * The four forms, for a `harnensemble` note writing `images/places/map.webp`
  * (`harnensemble` ships as the Foundry module `harn-ensemble`):
  *
  * | Form      | Address                                                       |
  * | --------- | ------------------------------------------------------------- |
- * | `foundry` | `modules/harn-ensemble/assets/images/map.webp`               |
- * | `local`   | `assets/images/map.webp`                                      |
+ * | `foundry` | `modules/harn-ensemble/images/map.webp`                      |
+ * | `local`   | `assets/images/places/map.webp`                               |
  * | `web`     | `https://cdn.heroiclands.org/harnensemble/images/map.webp`   |
- * | `pdf`     | `assets/images/map.webp`                                      |
+ * | `pdf`     | `assets/images/places/map.webp`                               |
+ *
+ * **Foundry and the website serve the deployed layout.** A suffix under
+ * `icons/` or `images/` reaches them flat — the type root and the basename,
+ * whatever directories the repository nests it in — because that is how the
+ * stage lays a package's pictures out and how the CDN holds them; see
+ * {@link module:engine/asset-shipping}. Every other suffix keeps its path, and
+ * sits under `assets/` in the install. `local` and `pdf` name the source file,
+ * so they keep the repository's own arrangement.
  *
  * **`<package>` and `<foundry-id>` are two different names.** The package is
  * `harnensemble` — what the content is called, what the website serves it under,
@@ -91,6 +99,7 @@
  */
 
 import { PACKAGEBUILD_PACKAGE } from "./packages.mjs";
+import { deployedSuffix, isDeployedSuffix } from "./asset-types.mjs";
 
 /**
  * The directory a package ships its files in, and the segment that marks a
@@ -146,7 +155,8 @@ export const PATHNAME_SURFACES = Object.freeze(["foundry", "local", "web", "pdf"
  *   package owns, `package` for an owned file.
  * @property {string|null} package  The content package that owns the file, or
  *   `null` when no package does.
- * @property {string|null} suffix  The path inside that package's shipped tree.
+ * @property {string|null} suffix  The path inside that package's `assets/`
+ *   directory, as its repository arranges it.
  * @property {boolean} own  Whether the owner is the package being built, and so
  *   whether `local` names a file this build may open.
  * @property {string|null} foundry  The address inside a Foundry install.
@@ -407,6 +417,10 @@ export function resolvePathname(raw, config) {
     const suffix = named ? segments.slice(2).join("/") : authored;
     const entry = owner ? packages.get(owner) : undefined;
     const host = String(config.site?.assets ?? "").replace(/\/+$/, "");
+    // A picture deploys flat at the package root; anything else keeps its
+    // path under the package's `assets/`.
+    const deployed = deployedSuffix(suffix);
+    const installed = isDeployedSuffix(suffix) ? deployed : `${ASSETS_SEGMENT}/${suffix}`;
 
     return {
         authored,
@@ -418,14 +432,11 @@ export function resolvePathname(raw, config) {
         // the first segment names a package this build has never heard of:
         // both are "there is no install path to derive", and guessing one
         // writes an address into a document nobody would check.
-        foundry:
-            entry?.root && entry.id ?
-                `${entry.root}/${entry.id}/${ASSETS_SEGMENT}/${suffix}`
-            :   null,
+        foundry: entry?.root && entry.id ? `${entry.root}/${entry.id}/${installed}` : null,
         local: `${ASSETS_SEGMENT}/${suffix}`,
         // `null` where no asset host is configured. The website is the one
         // surface whose address is not derivable from the repository itself.
-        web: host && owner ? `${host}/${owner}/${suffix}` : null,
+        web: host && owner ? `${host}/${owner}/${deployed}` : null,
         pdf: `${ASSETS_SEGMENT}/${suffix}`,
     };
 }

package/engine/rank-ladder.mjs

@@ -47,18 +47,47 @@ import { RUNG_FIELDS } from "./standing-terms.mjs";
 
 export { RUNG_FIELDS };
 
-/** Every affiliation has an ordinary standing that a being can name as rank 1. */
+/**
+ * Every affiliation's ladder has its two floor rungs: level 0, those the body
+ * excludes, and level 1, its ordinary members.
+ *
+ * A body that can name its members can name those it shuts out, whether or not
+ * it ever does, so both rungs are required of every ladder. A missing or empty
+ * ladder is one finding naming both; a ladder lacking either rung is one
+ * finding per rung it lacks, at the `ranks` key.
+ *
+ * @param {object} note - The note being checked.
+ * @param {string} note.file - Its path, as a diagnostic spells it.
+ * @param {string} [note.raw] - Its source, for the position.
+ * @param {object} [note.fm] - Its parsed frontmatter.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: string, message: string}>} The findings.
+ */
 export function checkAffiliationRankFloor(note) {
     if (note.fm?.type !== "affiliation") return [];
     const governance = note.fm?.data?.governance;
     const ranks = governance?.ranks;
     // A non-list already has a shape finding. Do not repeat it here.
     if (ranks !== undefined && ranks !== null && !Array.isArray(ranks)) return [];
-    if (
+    const has = (level) =>
         Array.isArray(ranks) &&
-        ranks.some((rung) => integer(rung?.level) && Number(rung.level) === 1)
-    )
-        return [];
+        ranks.some((rung) => integer(rung?.level) && Number(rung.level) === level);
+
+    const messages = [];
+    if (!Array.isArray(ranks) || ranks.length === 0) {
+        messages.push(
+            "affiliation needs data.governance.ranks with a level-0 rung naming those the " +
+                "body excludes and a level 1 standing for its members",
+        );
+    } else {
+        if (!has(1)) messages.push("affiliation data.governance.ranks needs a level 1 standing");
+        if (!has(0))
+            messages.push(
+                "data.governance.ranks must have a level-0 rung naming those the body " +
+                    "excludes, beside its level-1 members",
+            );
+    }
+    if (messages.length === 0) return [];
 
     const path = Array.isArray(ranks) ? ["data", "governance", "ranks"] : ["data", "governance"];
     const atRankOrGovernance = positionOfFrontmatterPath(note.raw ?? "", path, { key: true });
@@ -66,17 +95,12 @@ export function checkAffiliationRankFloor(note) {
         atRankOrGovernance.line !== undefined ?
             atRankOrGovernance
         :   positionOfFrontmatterPath(note.raw ?? "", ["data"], { key: true });
-    return [
-        {
-            file: note.file,
-            ...position,
-            severity: "error",
-            message:
-                !Array.isArray(ranks) || ranks.length === 0 ?
-                    "affiliation needs data.governance.ranks with a level 1 standing"
-                :   "affiliation data.governance.ranks needs a level 1 standing",
-        },
-    ];
+    return messages.map((message) => ({
+        file: note.file,
+        ...position,
+        severity: "error",
+        message,
+    }));
 }
 
 /**

package/engine/scenes.mjs

@@ -220,7 +220,7 @@ export class Scenes extends BasePackCompiler {
             // A scene that references nothing ships fine as a plain `scenes`
             // entry; only pins need the id-preserving import an Adventure gives.
             if (!place.pinned) continue;
-            this.writeTo(this.adventureDir, this.#buildAdventure(place));
+            this.writeTo(this.adventureDir, this.#buildAdventure(place), "Adventure");
             this.adventureCount++;
         }
     }

package/engine/standing-terms.mjs

@@ -82,7 +82,9 @@ export const RUNG_FIELDS = Object.freeze([
         kind: "integer",
         required: true,
         shape: "a whole number — the rung's position on this body's own ladder",
-        describe: "The rung's position on the ladder; a member's `rank` names it.",
+        describe:
+            "The rung's position on the ladder — `0` the excluded, `1` the ordinary member; " +
+            "a member's `rank` names it.",
     }),
     Object.freeze({
         name: "title",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.4.1",
+    "version": "23.5.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -136,6 +136,7 @@
         "@viz-js/viz": "^3.30.0",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
+        "aws4fetch": "^1.0.20",
         "classic-level": "^3.0.0",
         "dale-chall": "^2.0.1",
         "dotenv": "^18.0.0",
@@ -189,8 +190,8 @@
         "prepack": "run-s build:types build:asset-index",
         "build:types": "tsc -p tsconfig.dts.json",
         "build:asset-index": "node ci/emit-asset-index.mjs",
-        "format": "prettier --write .",
-        "format:check": "prettier --check .",
+        "format": "node ci/prettier.mjs --write",
+        "format:check": "node ci/prettier.mjs --check",
         "lint": "run-p --aggregate-output -c --max-parallel 4 format:check lint:markdown lint:yaml lint:labels lint:image-roles lint:banners lint:content-format lint:docs-links",
         "lint:markdown": "node bin/package-build.mjs markdown",
         "lint:docs-links": "node bin/package-build.mjs docs links",

package/packagebuild-metadata.jsonl

@@ -1,13 +1,13 @@
-{"address":{"canonical":{"address":"packagebuild-none-image-afflictionbnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/afflictionbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"afflictionbnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-armorclothingbnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/armorclothingbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"armorclothingbnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-attributebnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/attributebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"attributebnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-containerbnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/containerbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"containerbnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-devdocsbnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/devdocsbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"devdocsbnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-miscgearbnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/miscgearbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"miscgearbnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-mysticalabilitybnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/mysticalabilitybnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"mysticalabilitybnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-projectilebnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/projectilebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"projectilebnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-rulesbnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/rulesbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"rulesbnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-skillbnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/skillbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"skillbnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-traumabnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/traumabnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"traumabnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-userguidebnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/userguidebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"userguidebnr","type":"image"}
-{"address":{"canonical":{"address":"packagebuild-none-image-weapongearbnr","anchor":null,"anchorKind":null}},"asset":{"ai":false,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-afflictionbnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/afflictionbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"afflictionbnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-armorclothingbnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/armorclothingbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"armorclothingbnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-attributebnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/attributebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"attributebnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-containerbnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/containerbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"containerbnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-devdocsbnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/devdocsbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"devdocsbnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-miscgearbnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/miscgearbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"miscgearbnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-mysticalabilitybnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/mysticalabilitybnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"mysticalabilitybnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-projectilebnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/projectilebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"projectilebnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-rulesbnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/rulesbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"rulesbnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-skillbnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/skillbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"skillbnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-traumabnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/traumabnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"traumabnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-userguidebnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/userguidebnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"userguidebnr","type":"image"}
+{"address":{"canonical":{"address":"packagebuild-none-image-weapongearbnr","anchor":null,"anchorKind":null}},"asset":{"ai":true,"attribution":"Tom Rodriguez","height":768,"license":"CC-BY-SA-4.0","notes":"","path":"images/banners/weapongearbnr.webp","role":"","source":"","width":1792},"package":"packagebuild","shortcode":"weapongearbnr","type":"image"}

package/release.mjs

@@ -24,7 +24,10 @@
  * by what the manifest says, not chosen here — see `manifest.mjs`. A package
  * that publishes a DataModel schema (`packageBuild.schema`, staged through
  * `packageBuild.assets`) gets a fourth: `schema.json`, published whenever the
- * stage carries one and silently skipped otherwise.
+ * stage carries one and silently skipped otherwise. A package that stages
+ * pictures gets `icons.zip` and `images.zip` as well: each picture root of the
+ * stage with the package's asset set, `asset-sets/default.json`, for a GM
+ * placing the files by hand.
  *
  * Kept apart from `stage.mjs` because this is the only part of assembling a
  * package that needs a dependency. A repository that never cuts a release from
@@ -44,6 +47,7 @@ import path from "node:path";
 import { ZipArchive } from "archiver";
 
 import { SCHEMA_ARTIFACT_FILE } from "./engine/foreign-catalog.mjs";
+import { DEPLOYED_ASSET_TYPES, SHIPPED_SET_FILE } from "./engine/asset-shipping.mjs";
 
 /** The earliest instant a zip entry's date field can hold. */
 const ZIP_EPOCH_MS = Date.UTC(1980, 0, 1);
@@ -74,9 +78,10 @@ function archiveDate() {
  * @param {import("archiver").ZipArchive} archive
  * @param {string} root - The directory whose contents become the archive.
  * @param {Date} date - The date recorded on every entry.
+ * @param {string} [prefix] - Prepended to every entry's name, `/`-terminated.
  * @returns {Promise<void>}
  */
-async function appendTree(archive, root, date) {
+async function appendTree(archive, root, date, prefix = "") {
     /** @param {string} rel - Path relative to `root`, `/`-separated, or "". */
     async function walk(rel) {
         const entries = await fsp.readdir(path.join(root, rel), { withFileTypes: true });
@@ -88,11 +93,15 @@ async function appendTree(archive, root, date) {
         for (const entry of entries) {
             const name = rel ? `${rel}/${entry.name}` : entry.name;
             if (entry.isDirectory()) {
-                archive.append(Buffer.alloc(0), { name: `${name}/`, date, mode: 0o755 });
+                archive.append(Buffer.alloc(0), {
+                    name: `${prefix}${name}/`,
+                    date,
+                    mode: 0o755,
+                });
                 await walk(name);
             } else {
                 const body = await fsp.readFile(path.join(root, name));
-                archive.append(body, { name, date, mode: 0o644 });
+                archive.append(body, { name: `${prefix}${name}`, date, mode: 0o644 });
             }
         }
     }
@@ -123,9 +132,10 @@ async function appendTree(archive, root, date) {
  * @param {boolean} [opts.pdf] - Whether to build the books that ship beside the
  *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   schema?: string, pdfs: string[], pdfFindings: object[], pdfSkipped: string|null,
- *   bytes: number, version: string}>} The paths written, what the book build
- *   found, the archive's size, and the version the manifest declares.
+ *   schema?: string, pictures: string[], pdfs: string[], pdfFindings: object[],
+ *   pdfSkipped: string|null, bytes: number, version: string}>} The paths
+ *   written, what the book build found, the archive's size, and the version
+ *   the manifest declares. `pictures` is each picture archive written.
  *   `metadata` is absent when the manifest advertises no content index,
  *   `schema` is absent when the stage carries no `schema.json`, and `pdfs` is
  *   every book's PDF that was written, in declared order. `pdfSkipped` is
@@ -184,6 +194,7 @@ export async function packRelease({
 
     const metadata = await publishMetadataIndex({ manifest, stage, out, metadataDir });
     const schema = await publishSchemaAsset({ stage, out });
+    const pictures = await publishPictureArchives({ stage, out });
 
     // Last, and never fatal: the archive and the manifest are the release, and
     // a book that failed to set is a reported problem rather than a reason to
@@ -198,6 +209,7 @@ export async function packRelease({
         manifest: path.join(out, manifestName),
         ...(metadata ? { metadata } : {}),
         ...(schema ? { schema } : {}),
+        pictures,
         pdfs: book.pdfs,
         pdfFindings: book.findings,
         pdfSkipped: book.pdfs.length ? null : book.reason,
@@ -324,3 +336,53 @@ async function publishSchemaAsset({ stage, out }) {
     await fsp.copyFile(src, dest);
     return dest;
 }
+
+/**
+ * Zip each picture root of the stage, with its asset set, beside the
+ * archive — `icons.zip` and `images.zip`.
+ *
+ * Each archive unpacks at a location's root: `icons/` or `images/`, and the
+ * `asset-sets/default.json` listing every picture the package ships. A stage
+ * with no such set staged no pictures and publishes neither.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage - The staged tree.
+ * @param {string} opts.out - Where release assets are written.
+ * @returns {Promise<string[]>} The archives written.
+ */
+async function publishPictureArchives({ stage, out }) {
+    const list = path.join(stage, ...SHIPPED_SET_FILE.split("/"));
+    if (!fs.existsSync(list)) return [];
+    const written = [];
+    for (const { root } of DEPLOYED_ASSET_TYPES) {
+        const dir = path.join(stage, root);
+        if (!fs.existsSync(dir)) continue;
+        const zipPath = path.join(out, `${root}.zip`);
+        const output = fs.createWriteStream(zipPath);
+        const archive = new ZipArchive({ zlib: { level: 9 } });
+        const closed = new Promise((resolve, reject) => {
+            output.on("close", resolve);
+            output.on("error", reject);
+            archive.on("error", reject);
+            archive.on("warning", reject);
+        });
+        archive.pipe(output);
+        const date = archiveDate();
+        archive.append(Buffer.alloc(0), {
+            name: `${path.posix.dirname(SHIPPED_SET_FILE)}/`,
+            date,
+            mode: 0o755,
+        });
+        archive.append(await fsp.readFile(list), {
+            name: SHIPPED_SET_FILE,
+            date,
+            mode: 0o644,
+        });
+        archive.append(Buffer.alloc(0), { name: `${root}/`, date, mode: 0o755 });
+        await appendTree(archive, dir, date, `${root}/`);
+        await archive.finalize();
+        await closed;
+        written.push(zipPath);
+    }
+    return written;
+}

package/sohl/actors.mjs

@@ -55,7 +55,13 @@
  * @module
  */
 
-import { sohlField, resolveName, systemTemplatePriority, folderField } from "../engine/helpers.mjs";
+import {
+    sohlField,
+    resolveName,
+    systemTemplatePriority,
+    folderField,
+    resolveImg,
+} from "../engine/helpers.mjs";
 import { openingMasteryLevel } from "./skill-base.mjs";
 import { SystemActorCompiler, renderSection } from "../engine/actor-compiler.mjs";
 import { withDraftNotice } from "../engine/draft-notice.mjs";
@@ -84,9 +90,11 @@ const SYSTEM = SOHL_DOCUMENT_SUBTYPES.block;
 
 // Default art per actor **subtype**, applied when frontmatter supplies no `img`
 // / `portrait`. Beings default to the generic person icon; another subtype adds
-// its own entry here as the map gains a row for it.
+// its own entry here as the map gains a row for it. Each is an authored
+// pathname, resolved like any `img:`, so its Foundry path follows the deployed
+// layout of the package that ships it.
 const DEFAULT_IMG = {
-    being: "systems/sohl/assets/icons/game-icons/delapouite/person.svg",
+    being: "sohl/assets/icons/game-icons/delapouite/person.svg",
 };
 
 /**
@@ -313,7 +321,7 @@ export class Actors extends SystemActorCompiler {
         // The being's own default sits above the subtype's: only the note's
         // tags say whether it is a person or a creature, and only this pass
         // reads them.
-        const art = this.actorArt(fm, defaultActorImg(subType));
+        const art = this.actorArt(fm, resolveImg(defaultActorImg(subType)));
 
         const items = this.buildEmbeddedItems(itemsMap, id, fm, ctx);
 

package/sohl/default-item-art.mjs

@@ -38,10 +38,12 @@
  * Injecting the map through configuration instead would re-open that drift,
  * because the two sides would once more be free to disagree.
  *
- * **Paths name the package that owns the file**, as every pathname does: these
- * icons are the `sohl` package's, so they are written `sohl/assets/…` and each
- * surface derives its own address from that. If a new item type is added, add
- * its default here.
+ * **Values are the deployed form of the file's path**, `sohl/icons/<basename>`:
+ * the owning package's name, then the flat location a staged package serves its
+ * icons from. A runtime prefixes `systems/` and has a Foundry address.
+ * {@link defaultItemArt} returns the same file as an authored pathname,
+ * `sohl/assets/icons/<basename>`, which is what the build resolves through
+ * `resolveImg`. If a new item type is added, add its default here.
  *
  * **The keys are SoHL *document* subtypes, not markdown note types.** The
  * runtime reads this with `itemData.type`, which is a Foundry Item subtype, and
@@ -53,19 +55,19 @@
  * build translates once and no second copy of those three rows exists.
  */
 export const DEFAULT_ITEM_ART = {
-    affiliation: "sohl/assets/icons/noun/shieldnn.svg",
-    affliction: "sohl/assets/icons/other/sick.svg",
-    armorgear: "sohl/assets/icons/game-icons/lorc/breastplate.svg",
-    attribute: "sohl/assets/icons/game-icons/lorc/charm.svg",
-    concoctiongear: "sohl/assets/icons/game-icons/badges/flask.svg",
-    containergear: "sohl/assets/icons/other/sack.svg",
-    miscgear: "sohl/assets/icons/other/questionmark.svg",
-    mystery: "sohl/assets/icons/game-icons/delapouite/sparkles.svg",
-    mysticalability: "sohl/assets/icons/other/handsparkles.svg",
-    projectilegear: "sohl/assets/icons/noun/arrow.svg",
-    skill: "sohl/assets/icons/other/headgear.svg",
-    trauma: "sohl/assets/icons/other/injury.svg",
-    weapongear: "sohl/assets/icons/other/sword.svg",
+    affiliation: "sohl/icons/shieldnn.svg",
+    affliction: "sohl/icons/sick.svg",
+    armorgear: "sohl/icons/breastplate.svg",
+    attribute: "sohl/icons/charm.svg",
+    concoctiongear: "sohl/icons/flask.svg",
+    containergear: "sohl/icons/sack.svg",
+    miscgear: "sohl/icons/questionmark.svg",
+    mystery: "sohl/icons/sparkles.svg",
+    mysticalability: "sohl/icons/handsparkles.svg",
+    projectilegear: "sohl/icons/arrow.svg",
+    skill: "sohl/icons/headgear.svg",
+    trauma: "sohl/icons/injury.svg",
+    weapongear: "sohl/icons/sword.svg",
 };
 
 /**
@@ -80,7 +82,8 @@ export const DEFAULT_ITEM_ART = {
  *
  * @param {string} type - The SoHL Item document subtype — `armorgear`, not the
  *   `armor` note type that compiles into one.
- * @returns {string} the default image path for that subtype.
+ * @returns {string} the default image as an authored pathname,
+ *   `sohl/assets/icons/<basename>`.
  */
 export function defaultItemArt(type) {
     if (!(type in DEFAULT_ITEM_ART)) {
@@ -91,5 +94,6 @@ export function defaultItemArt(type) {
     // The map's inferred type has no index signature — deliberately, so callers
     // reading it directly get the precise key set. The `in` guard above has
     // already proved this key is present.
-    return /** @type {Record<string, string>} */ (DEFAULT_ITEM_ART)[type];
+    const deployed = /** @type {Record<string, string>} */ (DEFAULT_ITEM_ART)[type];
+    return deployed.replace("/icons/", "/assets/icons/");
 }

package/types/config.d.mts

@@ -102,6 +102,8 @@ export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
  * @property {string} stageDir      The staged package root, relative to
  *                                   `rootDir`. Every asset `to:` lands under it.
  * @property {readonly Readonly<AssetSpec>[]} assets
+ * @property {readonly string[]} shippingLicenses  Licences this package adds to the
+ *                                   default shipping list.
  * @property {boolean} baseStyles    Whether the package takes the shared base
  *                                   stylesheet, staged into `stageDir` and
  *                                   named first in the manifest's `styles`.
@@ -238,6 +240,11 @@ export type PackageBuildConfig = {
      */
     stageDir: string;
     assets: readonly Readonly<AssetSpec>[];
+    /**
+     * Licences this package adds to the
+     * default shipping list.
+     */
+    shippingLicenses: readonly string[];
     /**
      * Whether the package takes the shared base
      * stylesheet, staged into `stageDir` and