@heroiclands/package-build 21.1.0 → 22.0.0

package/sohl/note-schemas.mjs

@@ -146,26 +146,14 @@ const BEING_FIELDS = Object.freeze([
  * business; their authored vocabulary is the same, so they share one
  * declaration rather than three copies that could drift.
  *
- * `img` is the one required field — the compiler refuses a map note without it,
- * since a scene with no background is not a map. It was spelled `image` and
- * read from the `sohl:` block; both were read while the trees were
- * swept; that retirement has since completed and `image` is gone.
+ * `data.bgImage` is the one required piece of art — the compiler refuses a map
+ * note without it, since a scene with no background is not a map. It is
+ * declared in the note vocabulary rather than here, because it is an art slot
+ * like every other and a Scene has no `img` for the shared key to reach.
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
 const MAP_FIELDS = Object.freeze([
-    {
-        name: "img",
-        ...STRING,
-        required: true,
-        // Art is not system-specific — a Scene is a core Foundry document, and
-        // every other note type carries its `img` at the note's top level.
-        shared: true,
-        describe:
-            "The scene's background image. Owned by whichever package its first segment " +
-            "names — `systems/…` and `modules/…` are emitted unchanged, anything else is " +
-            "this package's own and is rooted under its assets.",
-    },
     {
         name: "dimensions",
         ...LIST,

package/types/content-config.d.mts

@@ -66,6 +66,7 @@ export const PACKAGE_KINDS: readonly ["systems", "modules", "documentation"];
 export const DOCUMENTATION_KIND: string;
 export namespace DEFAULT_PATHS {
     let content: "assets/content";
+    let assets: "assets";
     let contentIndex: "build/content-index";
     let packJson: "build/packs-json";
     let stage: "build/stage/packs";
@@ -299,6 +300,12 @@ export type PathsInput = {
      * Content tree root.
      */
     content?: string | undefined;
+    /**
+     * The asset roots' parent — the directory
+     *            holding `icons/`, `images/` and
+     *            `audio/`.
+     */
+    assets?: string | undefined;
     /**
      * Where `content-index` writes this
      *      package's note index. Outbound, and a
@@ -338,6 +345,7 @@ export type PathsInput = {
  */
 export type ResolvedPaths = {
     content: string;
+    assets: string;
     contentIndex: string;
     packJson: string;
     stage: string;

package/types/engine/actor-compiler.d.mts

@@ -182,6 +182,29 @@ export class SystemActorCompiler extends BasePackCompiler {
         itemsSourceDirs?: never[] | undefined;
         foreignSourceDirs?: never[] | undefined;
     });
+    /**
+     * The actor's two pieces of art, resolved, with the being default beneath
+     * them.
+     *
+     * **The default is chosen from the note's tags**, which only a compiler can
+     * read: a `character` falls back to one file and a `creature` to another,
+     * and both are addresses in the package that ships them. A tree whose index
+     * cannot answer that address — a dependency not yet fetched — falls through
+     * to the subtype's own default, so the document is never left with no art.
+     *
+     * `tokenIcon` unset follows `icon`, and the fallback is applied after
+     * resolution rather than before: a note naming an icon and no token icon
+     * means "the token wears the profile art", not "the token wears the
+     * default".
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} fallback - The subtype's own default art path.
+     * @returns {{img: string, token: string}} The two paths.
+     */
+    actorArt(fm: object, fallback: string): {
+        img: string;
+        token: string;
+    };
     /** @type {readonly string[]} */
     itemsSourceDirs: readonly string[];
     foreignSourceDirs: any;
@@ -260,6 +283,12 @@ export class SystemActorCompiler extends BasePackCompiler {
      * every embedded id exactly where it was.
      * Returns null if the descriptor cannot be resolved.
      *
+     * **An entry's `data:` is the authoring container, not a document field.**
+     * Its art slot is read here and the container itself goes no further, so an
+     * entry writing `data.icon` reaches the document as a resolved `img` and an
+     * entry writing none takes its type's default — the same two rules an item
+     * note compiles under, reached by the same functions.
+     *
      * @param {Map<string, object>} itemsMap - The predefined items, by address.
      * @param {string} actorId - The owning actor's id, seeding embedded ids.
      * @param {string} type - The **note** type the reference names.

package/types/engine/art-fields.d.mts

@@ -0,0 +1,192 @@
+/**
+ * The art slot one key names, or `undefined`.
+ *
+ * @param {unknown} key - The key under `data:`.
+ * @returns {ArtSlot|undefined} The slot.
+ */
+export function artSlot(key: unknown): ArtSlot | undefined;
+/**
+ * The address an authored art value names.
+ *
+ * @param {string} value - The value as authored.
+ * @param {string} defaultType - The type the field declares.
+ * @returns {string} A written address, which may be partial.
+ */
+export function artTarget(value: string, defaultType: string): string;
+/**
+ * The address space an asset reference resolves against, from a corpus.
+ *
+ * Shaped exactly as {@link module:engine/wikilinks.buildWikilinkIndex}'s result
+ * is in the parts a resolver reads, so the site, the book and the pack compilers
+ * answer one authored address the same way.
+ *
+ * **The note types belong in `types` as well as the asset ones.** Without them
+ * `being-thorn` does not parse as an address at all, and an embed naming a note
+ * is reported as an unknown type on one surface and as the wrong kind of type on
+ * another — one mistake, two verdicts, which is what the shared vocabulary
+ * exists to prevent.
+ *
+ * @param {readonly object[]} records - The corpus, from
+ *   {@link module:engine/content-index.indexRecordsFor}.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {{index?: Map<string, object>, packages?: Iterable<string>}} [opts.foreign] -
+ *   The vendored indexes a dependency published.
+ * @param {Iterable<string>} [opts.types] - The note types this tree knows.
+ * @returns {object} The index.
+ */
+export function assetAddressIndex(records?: readonly object[], { config, foreign, types }?: {
+    config?: object | undefined;
+    foreign?: {
+        index?: Map<string, object>;
+        packages?: Iterable<string>;
+    } | undefined;
+    types?: Iterable<string> | undefined;
+}): object;
+/**
+ * The asset one authored value names, or why it names none.
+ *
+ * The whole lookup in one place, because two callers need it and they need
+ * different halves of the answer: an art slot needs the record, and an embed
+ * needs to tell an address that resolves to nothing from one that reaches the
+ * wrong *kind* of type. Those are different mistakes with different fixes, and a
+ * single `null` would collapse them into one message.
+ *
+ * Local files answer first and foreign ones after, which is an ordering of maps
+ * rather than a precedence rule: an address carries its own package, so the two
+ * cannot both hold one.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type a bare value takes.
+ * @returns {{record: {package: string, asset: {path: string}}, pathname: string}
+ *   |{record: null, reason: string, type?: string}} The asset and the pathname
+ *   it is at, or a reason from
+ *   {@link module:engine/wikilink-syntax.LINK_FINDING_REASONS}.
+ */
+export function readAssetAddress(index: object, value: unknown, defaultType: string): {
+    record: {
+        package: string;
+        asset: {
+            path: string;
+        };
+    };
+    pathname: string;
+} | {
+    record: null;
+    reason: string;
+    type?: string;
+};
+/**
+ * The index record an art value resolves to, or `null`.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type the field declares.
+ * @returns {{package: string, asset: {path: string}}|null} The record.
+ */
+export function resolveArtRecord(index: object, value: unknown, defaultType: string): {
+    package: string;
+    asset: {
+        path: string;
+    };
+} | null;
+/**
+ * The pathname an art value names, in the form an authored one takes.
+ *
+ * Handing the result to {@link module:engine/helpers.resolveImg} is what puts an
+ * art address and a body image through one ownership rule. The two empties
+ * survive it unchanged: `null` and an absent key mean *no art named, apply the
+ * default*, and `""` means *ship blank on purpose*.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex}.
+ * @param {unknown} value - The value as authored.
+ * @param {string} defaultType - The type the field declares.
+ * @returns {{pathname: string|null, resolved: boolean}} The pathname, and
+ *   whether an address was actually answered — which tells a caller applying a
+ *   default apart from one whose address named nothing.
+ */
+export function artPathname(index: object, value: unknown, defaultType: string): {
+    pathname: string | null;
+    resolved: boolean;
+};
+/**
+ * The default art address a being's own tags choose, or `null`.
+ *
+ * `character` means a **person**, not a human, and `creature` everything else;
+ * a being carries exactly one of the two, which is what makes the choice a
+ * lookup rather than a precedence rule.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @returns {string|null} The address, or `null` for a note carrying neither tag.
+ */
+export function beingDefaultArt(fm: object): string | null;
+/**
+ * What an unresolved art address is reported as.
+ *
+ * One wording, so the four compilers that can meet the case do not each invent
+ * their own.
+ *
+ * @param {string} key - The key that was authored.
+ * @param {unknown} value - The value it carried.
+ * @param {string} defaultType - The type the field declares.
+ * @returns {string} The message.
+ */
+export function unresolvedArtMessage(key: string, value: unknown, defaultType: string): string;
+/**
+ * One art slot: the key a note authors, and the type a bare value takes.
+ *
+ * @typedef {object} ArtSlot
+ * @property {string} key - The key under `data:`.
+ * @property {string} type - The asset type a bare shortcode defaults to.
+ * @property {boolean} document - Whether the slot reaches a compiled document.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/**
+ * The four art slots, in the order the specification tabulates them.
+ *
+ * `banner` is the one that reaches no compiled document: it is the page's hero
+ * image, read by the site and by the book's section plates and by nothing else.
+ * That is what `document: false` states, and it is why the inert-art check
+ * skips it — a key that is *meant* to reach no document is not an inert key.
+ *
+ * @type {readonly ArtSlot[]}
+ */
+export const ART_SLOTS: readonly ArtSlot[];
+/**
+ * The art a being falls back to, by the kind it is tagged.
+ *
+ * Both files ship in `sohl`, under `assets/icons/other/`, and both are named
+ * here as addresses rather than as paths for the reason every art reference is:
+ * the address resolves to a record that carries the owning package, so a
+ * package borrowing the default gets the same file the system ships.
+ *
+ * **Only the compiler can choose between them**, because only the compiler
+ * reads the note's tags. A schema default is the last resort beneath this one,
+ * and covers a world document created by hand, which no note describes.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const BEING_DEFAULT_ART: Readonly<Record<string, string>>;
+/**
+ * One art slot: the key a note authors, and the type a bare value takes.
+ */
+export type ArtSlot = {
+    /**
+     * - The key under `data:`.
+     */
+    key: string;
+    /**
+     * - The asset type a bare shortcode defaults to.
+     */
+    type: string;
+    /**
+     * - Whether the slot reaches a compiled document.
+     */
+    document: boolean;
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};

package/types/engine/asset-index.d.mts

@@ -0,0 +1,92 @@
+/**
+ * Read a package's asset trees into index records.
+ *
+ * @param {string} assetsBase - The package's asset directory, the three roots'
+ *   parent. A directory that does not exist yields nothing: a package with no
+ *   art is ordinary.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the trees belong to.
+ * @param {object[]} [options.problems] - Supplied by a **reader**: a file that
+ *   cannot be addressed is pushed here as a diagnostic and skipped. Omitted, it
+ *   throws — the contract the emitter needs, since an index missing an asset
+ *   asserts that the address does not exist.
+ * @returns {Array<Record<string, any>>} One record per addressable file, in walk
+ *   order; the caller imposes the index's total order.
+ * @throws {Error} When a file cannot be addressed and no `problems` array was
+ *   supplied. `file` rides on the error.
+ */
+export function collectAssetRecords(assetsBase: string, { contentPackage, problems }: {
+    contentPackage: string;
+    problems?: object[] | undefined;
+}): Array<Record<string, any>>;
+/**
+ * The file a directory records provenance for its subtree in.
+ *
+ * @type {string}
+ */
+export const PROVENANCE_FILE: string;
+/**
+ * The suffix a per-file provenance sidecar carries.
+ *
+ * Appended to the **whole** filename, extension included — `anvil.svg.yaml`,
+ * not `anvil.yaml` — because the address holds one file whose format is free to
+ * change, and a sidecar named after the address alone would be orphaned the day
+ * an SVG became a WebP without anything saying so.
+ *
+ * @type {string}
+ */
+export const PROVENANCE_SIDECAR_SUFFIX: string;
+/**
+ * One field of the `asset` block.
+ *
+ * @typedef {object} AssetRecordField
+ * @property {string} name - The key inside `asset`.
+ * @property {"walk"|"provenance"} from - Where the value comes from: the walk
+ *   itself, or the provenance record resolved for the address.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/**
+ * Every field an `asset` block carries, in the order it is documented.
+ *
+ * **The emitter builds a record from this list**, rather than from a literal
+ * that a second list somewhere else would have to be kept in step with. So a
+ * field added here is emitted, a field removed here stops being emitted, and the
+ * completeness guard derives what it checks from the same declaration instead of
+ * hand-copying it.
+ *
+ * Every field is always present, blank where nothing states it. A fixed record
+ * shape is what lets a consumer read `asset.license` without branching on
+ * whether the package happened to record one, and blank is the honest answer to
+ * "what does this package say about where this file came from" when it says
+ * nothing.
+ *
+ * @type {readonly AssetRecordField[]}
+ */
+export const ASSET_RECORD_FIELDS: readonly AssetRecordField[];
+/**
+ * The keys a provenance file may declare.
+ *
+ * Derived from {@link ASSET_RECORD_FIELDS} rather than restated, so the file
+ * format and the record cannot disagree about which keys exist.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const PROVENANCE_KEYS: ReadonlySet<string>;
+/**
+ * One field of the `asset` block.
+ */
+export type AssetRecordField = {
+    /**
+     * - The key inside `asset`.
+     */
+    name: string;
+    /**
+     * - Where the value comes from: the walk
+     * itself, or the provenance record resolved for the address.
+     */
+    from: "walk" | "provenance";
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};

package/types/engine/asset-types.d.mts

@@ -0,0 +1,110 @@
+/**
+ * Whether a type name addresses a file rather than a note.
+ *
+ * The one test the rewrite scoping rests on: a rewrite rule may substitute an
+ * asset and nothing else, so a fourth asset type is covered by this answer
+ * rather than by editing a list somewhere else.
+ *
+ * @param {unknown} type - The type name.
+ * @returns {boolean} True for `icon`, `image` or `audio`.
+ */
+export function isAssetType(type: unknown): boolean;
+/**
+ * The asset type a root directory declares, or `undefined`.
+ *
+ * @param {unknown} root - A directory name below `paths.assets`.
+ * @returns {AssetType|undefined} The type it holds.
+ */
+export function assetTypeOfRoot(root: unknown): AssetType | undefined;
+/**
+ * Whether a filename can be an address at all.
+ *
+ * A shortcode is lowercase alphanumerics, so a version string, a hyphen or a
+ * date stamp in a basename means the file cannot be addressed. The build says so
+ * rather than inventing a shortcode for it.
+ *
+ * @param {string} shortcode - The basename with its extension removed.
+ * @returns {boolean} Whether it matches {@link ADDRESS_SEGMENT_PATTERN}.
+ */
+export function isAssetShortcode(shortcode: string): boolean;
+/**
+ * The `<system>` segment every asset address carries.
+ *
+ * Spelled here rather than imported from `engine/systems.mjs` so this module
+ * stays a leaf. The two are held to one value by the address round-trip guard,
+ * which reads both.
+ *
+ * @type {string}
+ */
+export const ASSET_SYSTEM: string;
+/**
+ * File extensions that make a file a picture, lowercase and dot-led.
+ *
+ * Foundry's own `IMAGE_FILE_EXTENSIONS`, because these files are installed into
+ * a Foundry data directory and a format Foundry will not display is not one this
+ * toolchain should hand it an address for.
+ *
+ * @type {readonly string[]}
+ */
+export const IMAGE_EXTENSIONS: readonly string[];
+/**
+ * File extensions that make a file a sound, lowercase and dot-led.
+ *
+ * Foundry's own `AUDIO_FILE_EXTENSIONS`, for the reason above.
+ *
+ * @type {readonly string[]}
+ */
+export const AUDIO_EXTENSIONS: readonly string[];
+/**
+ * One asset type: what it is called, which directory holds it, and which files
+ * in that directory are assets of it.
+ *
+ * @typedef {object} AssetType
+ * @property {string} type - The type name, and the third segment of an address.
+ * @property {string} root - The directory below `paths.assets` that holds it.
+ * @property {readonly string[]} extensions - Lowercase, dot-led.
+ * @property {string} describe - One line, for the author-facing reference.
+ */
+/**
+ * The three asset types, in address order.
+ *
+ * The directory is named for what it holds and the type for what an address
+ * reaches, so the two differ by a letter and the mapping is **declared** rather
+ * than derived from the name.
+ *
+ * `icon` and `image` are two types rather than one because an icon has to stay
+ * coherent drawn into a 32×32 slot while an image is unbounded — a fitness
+ * property of the asset itself. They therefore have separate shortcode
+ * namespaces, and `icon-anvil` and `image-anvil` are different addresses.
+ *
+ * @type {readonly AssetType[]}
+ */
+export const ASSET_TYPES: readonly AssetType[];
+/**
+ * Every asset type name.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const ASSET_TYPE_NAMES: ReadonlySet<string>;
+/**
+ * One asset type: what it is called, which directory holds it, and which files
+ * in that directory are assets of it.
+ */
+export type AssetType = {
+    /**
+     * - The type name, and the third segment of an address.
+     */
+    type: string;
+    /**
+     * - The directory below `paths.assets` that holds it.
+     */
+    root: string;
+    /**
+     * - Lowercase, dot-led.
+     */
+    extensions: readonly string[];
+    /**
+     * - One line, for the author-facing reference.
+     */
+    describe: string;
+};

package/types/engine/base-compiler.d.mts

@@ -129,6 +129,11 @@ export class BasePackCompiler {
     /**
      * @param {object} options
      * @param {string} options.contentBase - Root of the content tree.
+     * @param {string} [options.assetsBase] - The asset roots' parent, whose
+     *   files the art addresses resolve against. Stated beside `contentBase`
+     *   because the two move independently: a caller compiling a tree it
+     *   assembled states where that tree's files are, and one compiling the
+     *   repository's own leaves it to the configuration.
      * @param {string} options.dest - Where this pass writes its JSON.
      * @param {readonly string[]} options.skipDirectories - Directories the walk
      *   never descends into. Required: see {@link assertStatedScope}.
@@ -148,8 +153,9 @@ export class BasePackCompiler {
      *   over, derived once and shared by every pass. A pass handed none derives
      *   its own in `prepare`, and reports that corpus's problems itself.
      */
-    constructor({ contentBase, dest, skipDirectories, folderResolver, packName, packSystem, docType, router, routingReporter, corpus, }?: {
+    constructor({ contentBase, assetsBase, dest, skipDirectories, folderResolver, packName, packSystem, docType, router, routingReporter, corpus, }?: {
         contentBase: string;
+        assetsBase?: string | undefined;
         dest: string;
         skipDirectories: readonly string[];
         folderResolver?: ((address: string | null) => string | null) | undefined;
@@ -164,6 +170,12 @@ export class BasePackCompiler {
     });
     /** @type {string} */
     contentBase: string;
+    /**
+     * The asset roots' parent, whose files the art addresses resolve against.
+     *
+     * @type {string|undefined}
+     */
+    assetsBase: string | undefined;
     /** @type {string} */
     outputDir: string;
     /** @type {(path: string|null) => string|null} */
@@ -348,6 +360,35 @@ export class BasePackCompiler {
      *   that does not convert.
      */
     convertBody(fm: object, body: string): string;
+    /**
+     * The Foundry path one authored art address names, or `null`.
+     *
+     * **The two empties survive.** `null` and an absent key mean *no art named*,
+     * so the caller's own default applies with nullish coalescing; `""` means
+     * *ship blank on purpose* and no default may replace it. That is
+     * {@link module:engine/helpers.resolveImg}'s rule, reached through it rather
+     * than restated, which is also what puts an art address and a body image
+     * through one ownership rule.
+     *
+     * An address nothing answers is reported against the note and treated as
+     * unnamed, so the document takes its default rather than shipping a path
+     * that installs nowhere.
+     *
+     * @param {unknown} value - The value as authored.
+     * @param {string} key - The key it was authored at, for the message.
+     * @param {string} type - The asset type a bare value takes.
+     * @returns {string|null} The Foundry-relative path, `""` for a deliberate
+     *   blank, or `null` where the note names none.
+     */
+    artPathOf(value: unknown, key: string, type: string): string | null;
+    /**
+     * The Foundry path one art slot of a note names, or `null`.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} key - The slot's key under `data:`.
+     * @returns {string|null} As {@link BasePackCompiler#artPathOf}.
+     */
+    artPath(fm: object, key: string): string | null;
     /**
      * Reports a warning about the note being compiled.
      *

package/types/engine/compile-corpus.d.mts

@@ -3,6 +3,8 @@
  *
  * @param {object} opts - Options.
  * @param {string} opts.contentBase - Root of the content tree.
+ * @param {string} [opts.assetsBase] - The asset roots' parent, whose files the
+ *   art addresses resolve against. Defaults to the configured one.
  * @param {readonly string[]} opts.skipDirectories - The scope, stated by the
  *   caller as every corpus read requires.
  * @param {object} opts.router - The pack router this compile resolved. Shared
@@ -17,8 +19,9 @@
  *   sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
-export function buildCompileCorpus({ contentBase, skipDirectories, router, config, problems, }: {
+export function buildCompileCorpus({ contentBase, assetsBase, skipDirectories, router, config, problems, }: {
     contentBase: string;
+    assetsBase?: string | undefined;
     skipDirectories: readonly string[];
     router: object;
     config?: object | undefined;

package/types/engine/content-charset.d.mts

@@ -78,6 +78,10 @@ export function checkText(text: string, file: string): Array<{
  * theoretical exclusion — it was the first thing a run over `sohl-thalorna`
  * reported before the skip existed.
  *
+ * A finding names its file **relative to the working directory**, which is
+ * where a reader is standing and what `formatDiagnostic` emits. The content
+ * root is where the walk starts, not what a path is measured from.
+ *
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore