@heroiclands/package-build 24.0.2 → 24.0.3

package/types/content-config.d.mts

@@ -313,8 +313,7 @@ export type PathsInput = {
     unpack?: string | undefined;
     /**
      * Where a dependency declaring
-     *      `itemCatalog: true` or
-     *      `assetArchive: true` is unpacked.
+     *      `itemCatalog: true` is unpacked.
      *      Inbound, and fetched rather than
      *      committed.
      */
@@ -486,13 +485,6 @@ export type RelationshipSpec = {
      *  does not hold. Needs a `manifest`.
      */
     itemCatalog?: boolean | undefined;
-    /**
-     * Whether `deps fetch` unpacks this
-     * dependency's release archive for its
-     * asset bytes alone, building no item
-     * catalogue from it. Needs a `manifest`.
-     */
-    assetArchive?: boolean | undefined;
     /**
      * Whether `deps fetch` fetches this
      * dependency's content index. Default
@@ -504,16 +496,6 @@ export type RelationshipSpec = {
      * index.
      */
     contentIndex?: boolean | undefined;
-    /**
-     * Whether this dependency's asset
-     * tree answers this package's own asset
-     * addresses ahead of its local record.
-     * Default `false`. Refuses `contentIndex:
-     * false` on the same entry, since a
-     * replacement with no fetched index to
-     * check against resolves nothing.
-     */
-    assetReplacement?: boolean | undefined;
 };
 /**
  * How a generated documentation page is framed in the repository publishing it.

package/types/engine/dictionary-layout.d.mts

@@ -60,6 +60,11 @@ export const LAYOUT_REQUIRED_COLUMNS: Readonly<{
 export const COMMON_MARK: "\u2022";
 /** The word-entry span class whose Foundry rendering is a native TOC heading. */
 export const DICTIONARY_ENTRY_CLASS: "dictionary-entry";
+/**
+ * The class on every link an entry writes to another note, so a site can set
+ * the link as plain text where its target is not a page a reader can reach.
+ */
+export const LEXICAL_LINK_CLASS: "lexical-ref";
 export type LayoutOptions = {
     /**
      * - Whether an Address can be

package/types/engine/foreign-catalog.d.mts

@@ -11,20 +11,6 @@ export function itemCatalogRelationships(config: object): Array<{
     kind: string;
     verified: string | undefined;
 }>;
-/**
- * Every declared relationship that opted into supplying its release archive
- * for asset bytes alone, with no item catalogue built from it.
- *
- * @param {object} config - The resolved build configuration.
- * @returns {Array<{id: string, manifest: string, kind: string, verified: string|undefined}>}
- *   The opted-in relationships, in declaration order.
- */
-export function assetArchiveRelationships(config: object): Array<{
-    id: string;
-    manifest: string;
-    kind: string;
-    verified: string | undefined;
-}>;
 /**
  * The cache directory for one dependency at one version.
  *
@@ -109,26 +95,6 @@ export function fetchCatalog(config: object, rel: {
     id: string;
     manifest: string;
 }): Promise<string>;
-/**
- * Fetch one dependency's release archive for its asset bytes alone, building
- * no item catalogue from it.
- *
- * Idempotent: a complete cache for the resolved version is left alone. Where a
- * relationship also declares `itemCatalog: true`, {@link fetchCatalog} already
- * unpacked this same archive into this same cache directory, and
- * {@link fetchAllCatalogs} does not call this function for it — the two never
- * download the same bytes twice.
- *
- * @param {object} config - The resolved build configuration.
- * @param {{id: string, manifest: string, verified?: string}} rel - The
- *   declared relationship.
- * @returns {Promise<string>} The dependency's cache directory.
- */
-export function fetchAssetArchive(config: object, rel: {
-    id: string;
-    manifest: string;
-    verified?: string;
-}): Promise<string>;
 /**
  * Fill the cache from a locally built artifact rather than a release.
  *
@@ -202,10 +168,6 @@ export function fetchAllMetadata(config: object): Promise<number>;
 /**
  * Fetch every opted-in dependency. The `deps fetch` command.
  *
- * A relationship declaring both `itemCatalog: true` and `assetArchive: true`
- * is fetched once: {@link fetchCatalog} already unpacks the archive on its
- * way to extracting the item catalogue, so this skips the archive-only fetch
- * for any id {@link fetchCatalog} already handled.
  *
  * @param {object} config - The resolved build configuration.
  * @returns {Promise<number>} How many dependencies were fetched.

package/types/engine/language-rows.d.mts

@@ -215,7 +215,7 @@ export function joinRows(records: Iterable<Record<string, any>>): object[];
  */
 export function markRows(records: Iterable<Record<string, any>>): object[];
 /**
- * The `skeleton` rows: one per `data.sounds.skeleton` entry, `second` a list.
+ * The `skeleton` rows: one per `data.sounds.skeleton` entry, `second` and `third` lists.
  *
  * @param {Iterable<Record<string, any>>} records - Index records.
  * @returns {object[]}

package/types/engine/pdf-build.d.mts

@@ -14,33 +14,16 @@
  * a build from touching a path outside its own output.
  *
  * A file **this** package ships stages directly. A pathname naming another
- * package's file stages instead from a declared replacement's cached archive,
- * when `opts.resolveReplacement` — the pure function
- * {@link module:engine/asset-replacement.resolveAssetReplacement} —
- * answers it; `opts.foreignIndex` is the merged index that answer is read
- * against. A pathname naming a package no replacement carries it for, or a
- * URL, names something no build here can open — a build reaches no network —
- * and the caller reports it as a picture the book will not carry.
+ * package's file, or a URL, names something no build here can open — a build
+ * reaches no network — and the caller reports it as a picture the book will
+ * not carry.
  *
  * @param {string} src - The pathname, as authored.
  * @param {object} config - The resolved configuration.
- * @param {object} [opts]
- * @param {Map<string, object>} [opts.foreignIndex] - Every fetched
- *   dependency's own records, keyed by canonical address — the index a
- *   replacement's record is read out of.
- * @param {Function} [opts.resolveReplacement] - {@link
- *   module:engine/asset-replacement.resolveAssetReplacement}, or an
- *   equivalent a caller injects for a test. Omitted, a foreign pathname this
- *   package does not own stays declined exactly as it always has.
  * @returns {{from: string, to: string}|null} The file, and where under the
  *   output directory it is staged.
- * @throws {Error} When a declared replacement answers the address but its
- *   archive was never fetched.
  */
-export function stagedImagePath(src: string, config: object, opts?: {
-    foreignIndex?: Map<string, object> | undefined;
-    resolveReplacement?: Function | undefined;
-}): {
+export function stagedImagePath(src: string, config: object): {
     from: string;
     to: string;
 } | null;
@@ -134,10 +117,6 @@ export function listBookAssets({ config, version, out }?: {
  *   {@link module:engine/pdf-pages}.
  * @param {Function} [opts.readPages] - {@link
  *   module:engine/pdf-pages.readEntryPages}, for tests.
- * @param {Function} [opts.resolveReplacement] - {@link
- *   module:engine/asset-replacement.resolveAssetReplacement}, for tests.
- *   Loaded from that module otherwise, and only when a relationship declares
- *   `assetReplacement: true` — a build with none never imports it.
  * @returns {Promise<{built: boolean, reason: string|null, findings: object[],
  *   imageReports: object[], books: Array<{id: string, title: string,
  *   built: boolean, typ: string, pdf: string|null, stats: object}>,
@@ -149,7 +128,7 @@ export function listBookAssets({ config, version, out }?: {
  *   every declared book whichever was requested; both are empty when a book's
  *   selection could not be read.
  */
-export function buildPdf({ config, configPath, book, out, version, compile, readPages, resolveReplacement, }?: {
+export function buildPdf({ config, configPath, book, out, version, compile, readPages, }?: {
     config?: object | undefined;
     configPath?: string | undefined;
     book?: string | undefined;
@@ -157,7 +136,6 @@ export function buildPdf({ config, configPath, book, out, version, compile, read
     version?: string | undefined;
     compile?: boolean | undefined;
     readPages?: Function | undefined;
-    resolveReplacement?: Function | undefined;
 }): Promise<{
     built: boolean;
     reason: string | null;

package/types/engine/site-reach.d.mts

@@ -67,6 +67,17 @@ export function splitContent(html: string): {
  * @returns {string} The sections, or `""` when nothing is left.
  */
 export function pruneGenerated(html: string, outside: (href: string) => boolean): string;
+/**
+ * Entries' links set as plain text where they lead outside a set of pages.
+ * Each link is the only child of a span carrying the class.
+ *
+ * @param {string} html - A page body.
+ * @param {(href: string) => boolean} outside - Whether an `href` names a page
+ *   of the site that is not to be linked.
+ * @param {string} className - The class the entries' links carry.
+ * @returns {string} The body with each such `<a>` replaced by its content.
+ */
+export function unlinkEntries(html: string, outside: (href: string) => boolean, className: string): string;
 /**
  * The comment that separates a page's authored text from the sections the
  * build generated after it, in the HTML the renderer writes.

package/engine/asset-replacement.mjs

@@ -1,93 +0,0 @@
-/*
- * 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
- */
-
-/**
- * A declared replacement package's asset record, picked over the local one,
- * by address.
- *
- * A package may declare, on a `relationships.<kind>[]` entry, that a
- * dependency's asset tree answers its own asset addresses —
- * `assetReplacement: true` in `package-build.config.yaml`:
- *
- * ```yaml
- * relationships:
- *     requires:
- *         - id: thalornaaltart
- *           manifest: https://…/releases/latest/download/module.json
- *           assetReplacement: true
- *           contentIndex: true
- * ```
- *
- * `assetReplacement: true` opts that relationship in. `resolveAssetReplacement`
- * is what turns the declaration into an answer, one address at a time, against
- * four rules:
- *
- * 1. **Scoped to asset types.** A non-asset address, or one whose package
- *    segment is not the compiling package's own, resolves to `null` at once —
- *    tested with {@link module:engine/asset-types.isAssetType} rather than
- *    reimplemented. A being, an item or a lore note is never replaced this
- *    way.
- * 2. **Ordered, single pass.** Replacements are tried in declaration order —
- *    the order their relationships appear in `package-build.config.yaml` —
- *    and the first one carrying the address wins.
- * 3. **Never recursive.** A replacement's own output address is not itself
- *    looked up against another replacement: resolving
- *    `thalornaaltart-none-image-thorn` never asks whether something replaces
- *    `thalornaaltart`. This forecloses a cycle by construction — there is
- *    nothing to loop.
- * 4. **A miss falls through.** `null` means no declared replacement carries
- *    the address, and the caller falls back to the local address exactly as
- *    it does today. This function never decides that a missing replacement is
- *    an error; a caller that wants that is free to build it on the answer.
- *
- * This resolver answers a different question from
- * {@link module:engine/asset-bindings.checkForeignAssetBindings}: that check
- * validates an art module's own staged files against another package's
- * addresses, at that module's own build time. This one runs at the *replaced*
- * package's build, consulted by its book, and asks whether a declared
- * replacement carries an address this package would otherwise answer itself.
- *
- * @module
- */
-
-import { isAssetType } from "./asset-types.mjs";
-import { canonicalKey, readCanonicalKey } from "./content-address.mjs";
-
-/**
- * The replacement record for one asset address, or `null`.
- *
- * @param {string} address - A canonical asset address.
- * @param {object} opts
- * @param {string} opts.localPackage - The compiling package's own segment.
- * @param {readonly string[]} opts.replacements - The package segments of
- *   every relationship declaring `assetReplacement: true`, in declaration
- *   order.
- * @param {Map<string, object>} opts.index - The merged content index, keyed
- *   by canonical address.
- * @returns {{record: object, package: string}|null} The first replacement
- *   carrying the address, or `null` when none does.
- */
-export function resolveAssetReplacement(address, { localPackage, replacements, index }) {
-    const parts = readCanonicalKey(address);
-    if (!parts) return null;
-    if (!isAssetType(parts.type)) return null;
-    if (parts.package !== localPackage) return null;
-    for (const replacementPackage of replacements ?? []) {
-        const key = canonicalKey(replacementPackage, parts.system, parts.type, parts.shortcode);
-        const record = index?.get(key);
-        if (record?.asset?.path && record.package) {
-            return { record, package: replacementPackage };
-        }
-    }
-    return null;
-}

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

@@ -1,22 +0,0 @@
-/**
- * The replacement record for one asset address, or `null`.
- *
- * @param {string} address - A canonical asset address.
- * @param {object} opts
- * @param {string} opts.localPackage - The compiling package's own segment.
- * @param {readonly string[]} opts.replacements - The package segments of
- *   every relationship declaring `assetReplacement: true`, in declaration
- *   order.
- * @param {Map<string, object>} opts.index - The merged content index, keyed
- *   by canonical address.
- * @returns {{record: object, package: string}|null} The first replacement
- *   carrying the address, or `null` when none does.
- */
-export function resolveAssetReplacement(address: string, { localPackage, replacements, index }: {
-    localPackage: string;
-    replacements: readonly string[];
-    index: Map<string, object>;
-}): {
-    record: object;
-    package: string;
-} | null;