@heroiclands/package-build 20.6.0 → 21.0.0

package/engine/item-registry.mjs

@@ -170,11 +170,11 @@ export function itemFields(type, system) {
  * `defaultItemArt` was written for. Only the error's *owner* changed: it now
  * names the registry the consumer declares and can add to.
  *
- * **Resolved by the same rule a note's `img:` is.** The path goes through
- * {@link resolveImg}, so `icons/relic.svg` means the consumer's own asset root
- * in the registry exactly as it does on a note, and an already-served path
- * (`systems/sohl/assets/…`, as every SoHL default is) passes through untouched.
- * One spelling, one meaning, wherever it is written.
+ * **Resolved by the same rule a note's `img:` is.** The pathname goes through
+ * {@link resolveImg}, so `icons/relic.svg` means the consumer's own package in
+ * the registry exactly as it does on a note, and `sohl/assets/…` — as every
+ * SoHL default is written — names the `sohl` package's file wherever it is
+ * compiled. One spelling, one meaning, wherever it is written.
  *
  * @param {string} type - the item type.
  * @param {string} [system] - The system compiling it, where a build declares

package/engine/journals.mjs

@@ -50,7 +50,9 @@ import log from "loglevel";
 
 import { sohlField, makeId, resolveName, defaultStats, md, folderField } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
-import { anchorPageId } from "./wikilinks.mjs";
+import { anchorPageId, resolveReference } from "./wikilinks.mjs";
+import { infoboxesToHtml, linkToUuid } from "./infobox-render.mjs";
+import { noteInfoboxes } from "./infobox-registry.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { JOURNAL_TYPES } from "./ids.mjs";
 
@@ -277,6 +279,13 @@ export function buildPages(rawPages, entryId, noteName) {
  *   entry: a module may ship the same content for two systems, and each pack's
  *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
+ * @param {string} [params.infobox] - The note's infobox, already rendered to
+ *   HTML. Prepended to the entry's first page, which is where the format puts
+ *   it: the box is generated content in document order, before the prose, and
+ *   a Foundry page is narrow enough that inlining it is the only arrangement
+ *   that reads. It is **not** a page of its own — a page is what a UUID
+ *   addresses, and a summary a reader has to navigate to is a summary they do
+ *   not see.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
 export function buildJournalEntry({
@@ -287,9 +296,13 @@ export function buildJournalEntry({
     folder = null,
     flags,
     stats = defaultStats(),
+    infobox = "",
 }) {
     const rawPages = splitPages(markdown, leadName);
     const pages = buildPages(rawPages, id, name);
+    if (infobox.trim() && pages.length) {
+        pages[0].text.content = `${infobox}\n${pages[0].text.content}`;
+    }
     return {
         name,
         pages,
@@ -422,10 +435,18 @@ export class Journals extends BasePackCompiler {
         const { value: authoredFolder } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress: true });
 
+        // What the note summarises, in the panel every medium draws from one
+        // definition. Links are compendium references rather than website
+        // URLs: a player reading this at the table stays in Foundry.
+        const boxes = noteInfoboxes(fm, {
+            resolve: (ref, hint) => resolveReference(this.linkIndex, ref, hint),
+        });
+
         return buildJournalEntry({
             id,
             name,
             markdown,
+            infobox: infoboxesToHtml(boxes, { link: linkToUuid }),
             // A doc-carrying note's lead page is the document itself, not an
             // "Introduction" — see {@link splitPages}.
             leadName: ownsDoc ? name : undefined,

package/engine/map-notes.mjs

@@ -59,6 +59,7 @@ import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.m
 // A map's background art is `img`, as every other note type's art is. `image`,
 // the spelling a map alone once used, is retired and gone.
 import { sohlField } from "./frontmatter.mjs";
+import { resolveImg } from "./helpers.mjs";
 
 /* -------------------------------------------------------------------- */
 /*  Note types and their canvas profiles                                */
@@ -907,7 +908,7 @@ export function buildScene(fm, ctx) {
     // Read from the note rather than from its `sohl:` block: art is not
     // system-specific, so `img` is authored at the top level like every other
     // type's, and `sohlField` honours the block for anything already there.
-    const img = sohlField(fm, "img");
+    const img = resolveImg(sohlField(fm, "img"));
     if (!img) throw new Error("a map note needs an `img`");
 
     const warn = (message) => {
@@ -985,7 +986,7 @@ export function buildScene(fm, ctx) {
  *   still works.
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl, sceneId, img = sohlField({ sohl }, "img")) {
+export function buildLevel(sohl, sceneId, img = resolveImg(sohlField({ sohl }, "img"))) {
     const level = {
         _id: DEFAULT_LEVEL_ID,
         name: sohl.levelName ?? "Ground",
@@ -994,7 +995,9 @@ export function buildLevel(sohl, sceneId, img = sohlField({ sohl }, "img")) {
             color: sohl.backgroundColor ?? "#999999",
             src: img,
         },
-        foreground: { src: sohl.overlay ?? null },
+        // The overlay is a pathname like the background, and resolves by the
+        // same rule — a scene draws the two from one authored statement each.
+        foreground: { src: resolveImg(sohl.overlay ?? null) },
         sort: 0,
         _key: `!scenes.levels!${sceneId}.${DEFAULT_LEVEL_ID}`,
     };
@@ -1117,7 +1120,9 @@ export function buildTiles(sohl, geom, ctx) {
             rotation: spec.rotation ?? 0,
             alpha: spec.alpha ?? 1,
             sort: 0,
-            texture: { src: spec.image },
+            // A tile's texture is a pathname, resolved by the same rule the
+            // scene's own background is.
+            texture: { src: resolveImg(spec.image) },
             _key: `!scenes.tiles!${ctx.sceneId}.${id}`,
         };
     });
@@ -1146,7 +1151,8 @@ export function buildSounds(sohl, geom, ctx) {
             x,
             y,
             radius: spec.radius ?? 0,
-            path: spec.path,
+            // An ambient sound is a file a package ships, like the pictures.
+            path: resolveImg(spec.path),
             repeat: spec.repeat ?? true,
             volume: spec.volume ?? 0.5,
             walls: spec.walls ?? true,

package/engine/metadata-index.mjs

@@ -362,6 +362,11 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 doc: record.documentation ?? undefined,
                 anchors: foundry?.anchors,
                 type: parts.type,
+                // What the note *is*, not only where it lives. A consumer
+                // grouping a reference by the family its target declares —
+                // an infobox sorting a being's skills — has no other way to
+                // learn it about a note another package publishes.
+                subType: record.subType ?? undefined,
                 package: pkg,
             });
         }

package/engine/note-vocabulary.mjs

@@ -262,6 +262,21 @@ export const DRAFT_TAG = "draft";
  * Kind and character are separate groups because one slot could not hold both: a
  * fishing village is a `village` that is `fishing`, and the single-valued field
  * this replaced had to spell it `Fishing Village` as a value of its own.
+ *
+ * **A group carrying `exclusive` is a single-valued slot**, and that is the one
+ * closure a tag vocabulary can make. Its tags are not several things the subject
+ * may be at once — they are the alternative answers to one question, so a note
+ * naming two of them has named none, and both together are refused as an error.
+ * The property is opt-in and changes nothing for a group without it: a place is
+ * freely a `port` and a `town`, and `draft` is orthogonal to everything. The
+ * value is what the slot is called, for the message a reader gets.
+ *
+ * **Closure stops at the slot, and deliberately.** A tag outside an exclusive
+ * group's list does not fill that group's slot and is not refused for failing
+ * to — `tags:` is open and a being tagged `undead` is describing the subject in
+ * the author's own words. What is refused is a near miss of a declared value,
+ * and two values of one slot; there is no third refusal to make without taking
+ * back the openness of the region these tags sit in.
  */
 export const DECLARED_TAGS = Object.freeze({
     /** What a place *is*. */
@@ -343,6 +358,15 @@ export const DECLARED_TAGS = Object.freeze({
             "unguilded",
         ]),
     }),
+    /**
+     * What kind of being this is — a person, or one of the beasts and made
+     * things. A being is one or the other, so the group is a slot.
+     */
+    beingKind: Object.freeze({
+        types: ["being"],
+        exclusive: "kind",
+        tags: Object.freeze(["character", "creature"]),
+    }),
     /** A note's working state, which any note may carry. */
     state: Object.freeze({ types: null, tags: Object.freeze([DRAFT_TAG]) }),
 });
@@ -355,8 +379,39 @@ export const DECLARED_TAGS = Object.freeze({
  * @returns {readonly string[]} The tags, in declaration order.
  */
 export function declaredTags(type, groups = DECLARED_TAGS) {
-    const applies = Object.values(groups).filter((g) => !g.types || g.types.includes(type));
-    return Object.freeze(applies.flatMap((g) => g.tags));
+    return Object.freeze(applicableTagGroups(type, groups).flatMap((g) => g.tags));
+}
+
+/**
+ * The declared groups scoped to this type, in declaration order.
+ *
+ * The one reading of `types` that the flattened list and the slot check share,
+ * so the two can never disagree about which groups a `being` is held to.
+ *
+ * @param {string} type - The note's type.
+ * @param {object} [groups] - The grouped declaration.
+ * @returns {object[]} The groups that apply.
+ */
+export function applicableTagGroups(type, groups = DECLARED_TAGS) {
+    return Object.values(groups).filter((g) => !g.types || g.types.includes(type));
+}
+
+/**
+ * The single-valued slots a note of this type has, in declaration order.
+ *
+ * A group carrying `exclusive` states alternatives rather than attributes, so a
+ * note carrying two of its tags has answered one question twice. Only such a
+ * group is returned: the check has nothing to say about a group whose tags
+ * genuinely accumulate.
+ *
+ * @param {string} type - The note's type.
+ * @param {object} [groups] - The grouped declaration.
+ * @returns {{slot: string, tags: readonly string[]}[]} The slots and their values.
+ */
+export function exclusiveTagGroups(type, groups = DECLARED_TAGS) {
+    return applicableTagGroups(type, groups)
+        .filter((g) => g.exclusive)
+        .map((g) => ({ slot: g.exclusive, tags: g.tags }));
 }
 
 /**

package/engine/pathnames.mjs

@@ -0,0 +1,374 @@
+/*
+ * 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>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * One authored pathname, and the four addresses it resolves to.
+ *
+ * A note names a file once — in `img:`, in `data.portrait:`, in the body of a
+ * markdown image — and four surfaces have to serve it: a Foundry install, this
+ * repository's own working tree, the website, and the book. Each addresses the
+ * same file differently, so the authored pathname is a *statement of
+ * ownership* and every surface derives its own address from it. One statement,
+ * four derivations, one rule.
+ *
+ * ## The rule
+ *
+ * **The first segment says which package owns the file, when it is followed by
+ * `assets/`.** Everything after `assets/` is the *suffix* — the path inside
+ * that package's shipped tree, and the one piece every form is built from.
+ *
+ * | Authored                    | Owner            | Suffix              |
+ * | --------------------------- | ---------------- | ------------------- |
+ * | `sohl/assets/icons/a.svg`   | the `sohl` package | `icons/a.svg`     |
+ * | `images/beings/b.webp`      | **this** package | `images/beings/b.webp` |
+ *
+ * A pathname that does not open with `<package>/assets/` belongs to the package
+ * 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 `thalorna` note writing `images/map.webp` (`thalorna`
+ * ships as the Foundry module `sohl-thalorna`):
+ *
+ * | Form      | Address                                            |
+ * | --------- | -------------------------------------------------- |
+ * | `foundry` | `modules/sohl-thalorna/assets/images/map.webp`      |
+ * | `local`   | `assets/images/map.webp`                            |
+ * | `web`     | `https://cdn.heroiclands.org/thalorna/images/map.webp` |
+ * | `pdf`     | `assets/images/map.webp`                            |
+ *
+ * **`<package>` and `<foundry-id>` are two different names.** The package is
+ * `thalorna` — what the content is called, what the website serves it under,
+ * and what a note writes. The Foundry id is `sohl-thalorna` — what Foundry
+ * installs the module as, and the only place that name appears. They coincide
+ * for `sohl` and `hm3`, which is exactly why the two are kept apart here rather
+ * than treated as one value.
+ *
+ * `local` and `pdf` read the same and mean different places: `local` is the file
+ * in the owning repository's working tree, `pdf` is where the book stages a copy
+ * beside its Typst source. They are derived separately because only one of them
+ * is a file a build may open — see {@link PathnameForms.own}.
+ *
+ * ## What is not a package pathname
+ *
+ * **An off-install address passes through on every surface**: a URL, a
+ * protocol-relative `//host/…`, or a `/`-rooted path, which Foundry serves from
+ * the data root and which names no package at all. That is how a note addresses
+ * core Foundry art (`/icons/svg/mystery-man.svg`) or a package this build knows
+ * nothing about (`/systems/dnd5e/icons/spell.webp`).
+ *
+ * **A package this build has never heard of keeps its ownership.** The website
+ * and the book need only the package's name and the suffix, so both resolve;
+ * the Foundry address needs the package's kind and its Foundry id, which only a
+ * declared relationship carries, so that one form comes back `null` and the
+ * caller that needs it refuses. Reading such a pathname as this package's own
+ * would file one package's name inside another's tree and say nothing.
+ *
+ * **A `systems/…` or `modules/…` pathname is refused.** It is a Foundry address
+ * written where an ownership statement belongs: it resolves for Foundry and for
+ * nothing else, because neither the website nor the book has any such directory.
+ * {@link pathnameProblem} names the replacement, and every surface refuses the
+ * value rather than deriving an address from it — a wrong address that resolves
+ * to a 404 is the failure this module exists to remove, and inventing one here
+ * would reintroduce it one directory along.
+ *
+ * ## The two empties
+ *
+ * `null` — or an absent key, which arrives as `undefined` — means **unset**: the
+ * note names no file and the caller's default applies. `""` means **blank on
+ * purpose**: the note names no file and wants none, so no default may replace
+ * it. `resolvePathname` returns `null` for the first and a form object whose
+ * every address is `""` for the second, so the two stay distinguishable all the
+ * way to the caller.
+ *
+ * @module
+ */
+
+/**
+ * The directory a package ships its files in, and the segment that marks a
+ * pathname's first segment as a package name.
+ *
+ * One constant rather than a literal in six places: it is the second segment of
+ * an authored package pathname, the last segment of a Foundry asset root, the
+ * whole of the `local` form's prefix, and the directory the book stages into.
+ *
+ * @type {string}
+ */
+export const ASSETS_SEGMENT = "assets";
+
+/**
+ * The Foundry roots that mark a pathname as written in Foundry's own spelling.
+ *
+ * `worlds/` is left out for the reason it was always left out: a package may not
+ * ship files out of a world, so a note writing one has made a different mistake
+ * and gets the ordinary "this package owns it" reading, which yields a plainly
+ * broken path rather than a plausible one.
+ *
+ * @type {readonly string[]}
+ */
+const FOUNDRY_ROOTS = Object.freeze(["systems", "modules"]);
+
+/**
+ * The relationship kinds whose packages a note may address.
+ *
+ * `conflicts` is absent: a package this one cannot run beside is not one whose
+ * artwork it cites.
+ *
+ * @type {readonly string[]}
+ */
+const ADDRESSABLE_RELATIONSHIPS = Object.freeze(["systems", "requires", "recommends"]);
+
+/**
+ * The surfaces one authored pathname resolves for.
+ *
+ * Exported so a test can assert that every form a resolution carries is one of
+ * these, and that none is missing — the guard against a fifth surface being
+ * added to one caller and forgotten in the resolver.
+ *
+ * @type {readonly string[]}
+ */
+export const PATHNAME_SURFACES = Object.freeze(["foundry", "local", "web", "pdf"]);
+
+/**
+ * One authored pathname, resolved.
+ *
+ * @typedef {object} PathnameForms
+ * @property {string} authored  The pathname exactly as the note wrote it.
+ * @property {"blank"|"external"|"package"} state  `blank` for `""`, `external`
+ *   for an address no 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 {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.
+ * @property {string|null} local  The file in the owning repository's tree.
+ * @property {string|null} web  The address the website serves.
+ * @property {string|null} pdf  Where the book stages its copy.
+ */
+
+/**
+ * Whether a pathname addresses something outside every package.
+ *
+ * Three shapes, each a different kind of "no package owns this": a URI scheme
+ * (`https:`, `data:`), a protocol-relative `//host/…`, and a `/`-rooted path,
+ * which Foundry serves from the data root rather than from any package.
+ *
+ * @param {string} s - A non-empty authored pathname.
+ * @returns {boolean} Whether every surface emits it unchanged.
+ */
+function isExternal(s) {
+    // Checked before the single-slash case, which would otherwise claim it.
+    if (s.startsWith("//")) return true;
+    if (s.startsWith("/")) return true;
+    return /^[a-z][a-z0-9+.-]*:/i.test(s);
+}
+
+/**
+ * The pathname a Foundry-spelled one should be written as.
+ *
+ * Both shapes a tree carries fold into the same answer: a served path that
+ * already names an `assets/` directory keeps its suffix, and one that does not —
+ * `hm3` serves its pictures from `images/` at its own root — gains the segment,
+ * because `assets/` is where a package's files sit in every form this module
+ * derives.
+ *
+ * @param {string} s - A pathname opening with a Foundry root.
+ * @returns {string} What to write instead.
+ */
+function convertedSpelling(s) {
+    const [, id, ...rest] = s.split("/");
+    const tail = rest.join("/");
+    if (rest[0] === ASSETS_SEGMENT) return `${id}/${tail}`;
+    return `${id}/${ASSETS_SEGMENT}/${tail}`;
+}
+
+/**
+ * What is wrong with an authored pathname, or `""` when nothing is.
+ *
+ * Config-free, and a sentence rather than a code, so the lint that has a line
+ * and a column to attach it to and the resolver that has only a file say the
+ * same thing about the same value.
+ *
+ * @param {string|null|undefined} raw - The pathname, as authored.
+ * @returns {string} The problem, as a finding's sentence, or `""`.
+ */
+export function pathnameProblem(raw) {
+    if (raw == null) return "";
+    const s = String(raw);
+    if (!s || isExternal(s)) return "";
+    const root = s.split("/")[0];
+    if (!FOUNDRY_ROOTS.includes(root)) return "";
+    return (
+        `\`${s}\` is a Foundry address — write \`${convertedSpelling(s)}\`. A pathname ` +
+        "names the package that owns the file and the path inside that package's " +
+        "`assets/`, and each surface derives its own address from it: Foundry gets " +
+        "the path inside the install, the website gets one on the asset host, and " +
+        "the book gets a staged copy. A `" +
+        `${root}/` +
+        "` path is only one of those three, so the other two serve a file that " +
+        "is not there"
+    );
+}
+
+/**
+ * Every game system this build compiles content for.
+ *
+ * Four declarations say so, and a package makes whichever of them its situation
+ * calls for: `systems:` states a system it stamps content against, `packs[].system`
+ * gates a pack on one, `requiresSystem` restricts the package to one, and
+ * `relationships.systems` names one in the shipped manifest. `harn-ensemble`
+ * ships an HM3 pack and a SoHL pack and declares neither relationship, because
+ * naming a system in a relationship is what would stop Foundry loading the
+ * module in the other one's world — so reading any single declaration would
+ * miss the package whose content cites both systems' artwork.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {string[]} The system ids, deduplicated.
+ */
+function declaredSystemIds(config) {
+    return [
+        ...new Set(
+            [
+                ...Object.keys(config.systems ?? {}),
+                config.requiresSystem,
+                ...(config.packs ?? []).map((pack) => pack.system),
+                ...(config.relationships?.systems ?? []).map((rel) => rel.id),
+            ].filter(Boolean),
+        ),
+    ];
+}
+
+/**
+ * Every content package this build can resolve a pathname against.
+ *
+ * The package being built; every game system it compiles content for, which
+ * Foundry serves from `systems/<id>`; and every other package it declares a
+ * relationship with, which states that package's Foundry id and — where the two
+ * words differ — what its content is called.
+ *
+ * @param {object} config - The resolved build configuration.
+ * @returns {Map<string, {root: string|null, id: string|null, own: boolean}>} The
+ *   packages, by content package name. `root` is the Foundry directory the
+ *   package is served from, `null` where the package ships no Foundry package.
+ */
+export function packageAddresses(config) {
+    /** @type {Map<string, {root: string|null, id: string|null, own: boolean}>} */
+    const out = new Map();
+    if (config.contentPackage) {
+        out.set(config.contentPackage, {
+            // `assetRoot` is `<root>/<id>/assets`, and `null` for a
+            // `documentation` package — which is the same "Foundry serves no
+            // files for this" the `root` below says.
+            root: config.assetRoot ? config.packageKind : null,
+            id: config.foundryPackage ?? null,
+            own: true,
+        });
+    }
+    // The package being built wins every collision: it is the one whose files
+    // this repository actually holds, and another declaration of the same name
+    // describes that very package from outside.
+    for (const id of declaredSystemIds(config)) {
+        if (out.has(id)) continue;
+        out.set(id, { root: "systems", id, own: false });
+    }
+    for (const kind of ADDRESSABLE_RELATIONSHIPS) {
+        for (const rel of config.relationships?.[kind] ?? []) {
+            const name = rel.contentPackage ?? rel.id;
+            if (out.has(name)) continue;
+            const type = rel.type ?? (kind === "systems" ? "system" : "module");
+            out.set(name, { root: `${type}s`, id: rel.id, own: false });
+        }
+    }
+    return out;
+}
+
+/**
+ * Resolve one authored pathname into the address each surface serves.
+ *
+ * @param {string|null|undefined} raw - The pathname, as authored.
+ * @param {object} config - The resolved build configuration. Required rather
+ *   than defaulted, which is what keeps this module a leaf: it reads a
+ *   configuration and never loads one, so the lint can import it without a
+ *   repository to resolve.
+ * @returns {PathnameForms|null} The four forms, or `null` when the note names
+ *   no file at all.
+ * @throws {Error} When the pathname is written in Foundry's own spelling, which
+ *   resolves on one surface and nowhere else.
+ */
+export function resolvePathname(raw, config) {
+    if (raw == null) return null;
+    const authored = String(raw);
+    if (authored === "") {
+        return {
+            authored,
+            state: "blank",
+            package: null,
+            suffix: null,
+            own: false,
+            foundry: "",
+            local: "",
+            web: "",
+            pdf: "",
+        };
+    }
+    if (isExternal(authored)) {
+        return {
+            authored,
+            state: "external",
+            package: null,
+            suffix: null,
+            own: false,
+            foundry: authored,
+            local: authored,
+            web: authored,
+            pdf: authored,
+        };
+    }
+    const problem = pathnameProblem(authored);
+    if (problem) throw new Error(`package-build: ${problem}.`);
+
+    const packages = packageAddresses(config);
+    const segments = authored.split("/");
+    // The first segment names a package when an `assets/` follows it. That is
+    // the whole test, and it is deliberately not "when the name is one this
+    // build knows": a pathname whose owner this build has never heard of still
+    // has a package, a suffix, and a correct address on the website, and
+    // reading it as this package's own would put one package's name inside
+    // another's tree and report nothing.
+    const named = segments.length > 2 && segments[1] === ASSETS_SEGMENT ? segments[0] : "";
+    const owner = named || (config.contentPackage ?? null);
+    const suffix = named ? segments.slice(2).join("/") : authored;
+    const entry = owner ? packages.get(owner) : undefined;
+    const host = String(config.site?.assets ?? "").replace(/\/+$/, "");
+
+    return {
+        authored,
+        state: "package",
+        package: owner,
+        suffix,
+        own: entry?.own === true,
+        // `null` where the owning package ships no Foundry package, and where
+        // 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,
+        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,
+        pdf: `${ASSETS_SEGMENT}/${suffix}`,
+    };
+}