@heroiclands/package-build 0.6.1 → 3.0.0

package/types/engine/helpers.d.mts

@@ -0,0 +1,348 @@
+/**
+ * Parses a markdown file with YAML frontmatter.
+ *
+ * Returns `{ frontmatter, body, description, bodyLine, bodyColumn }` where
+ * `body` is the trimmed raw markdown after the frontmatter block, and
+ * `description` is `body` rendered to HTML. `bodyLine` / `bodyColumn` are the
+ * 1-based **file** position of the body's first character, which is what turns
+ * an offset within `body` into a position a diagnostic can name (#17) — see
+ * {@link positionInBody}. If the file has no frontmatter block, returns
+ * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
+ * position: there is no body to have one.
+ */
+export function parseMarkdownFile(filePath: any): {
+    frontmatter: null;
+    body: string;
+    description: string;
+    bodyLine?: undefined;
+    bodyColumn?: undefined;
+} | {
+    frontmatter: any;
+    body: string;
+    description: any;
+    bodyLine: number;
+    bodyColumn: number;
+};
+/**
+ * Recursively yields every `.md` file under `rootDir`, parsed.
+ * Yields `{ frontmatter, body, description, file, absPath, bodyLine,
+ * bodyColumn }` for each match — the last two from
+ * {@link parseMarkdownFile}, so a caller can report a position inside the
+ * body as a position in the file (#17).
+ * Silently skips directories that don't exist.
+ *
+ * Directory names in `skipDirectories` are ignored wherever they appear. The
+ * walk itself knows nothing about what they mean: `Templates/` is an Obsidian
+ * templater convention this repository's vault happens to use, not a property
+ * of a content tree, so it is configured rather than hard-coded (#1508).
+ *
+ * @param {string} rootDir - Root of the tree to walk.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
+ *   Defaults to the configured list.
+ */
+export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
+    skipDirectories?: readonly string[] | undefined;
+}): Generator<{
+    file: string & NonSharedBuffer;
+    absPath: string;
+    frontmatter: null;
+    body: string;
+    description: string;
+    bodyLine?: undefined;
+    bodyColumn?: undefined;
+} | {
+    file: string & NonSharedBuffer;
+    absPath: string;
+    frontmatter: any;
+    body: string;
+    description: any;
+    bodyLine: number;
+    bodyColumn: number;
+}, void, unknown>;
+/**
+ * Resolve the required `sohl.archetype` frontmatter for an Item/Actor entry
+ * (see the archetype contract, #604 — `flags.sohl.docArchetype`). The property
+ * is a nullable number that authors must state explicitly:
+ *   - a number → the document is an archetype of that priority.
+ *   - `null`   → the document is not an archetype.
+ *   - absent   → an authoring error (throws), so "not an archetype" is never
+ *                silently assumed.
+ *
+ * Reads `sohl.archetype`, falling back to a top-level `archetype` key to match
+ * {@link sohlField}'s nested-then-top-level resolution.
+ *
+ * @param {object} fm      Parsed frontmatter.
+ * @param {string} label   Human-readable context for error messages.
+ * @returns {number|undefined}  The archetype priority, or `undefined` when null.
+ * @throws {Error} When `sohl.archetype` is absent or is not a number/null.
+ */
+export function resolveArchetype(fm: object, label: string): number | undefined;
+/**
+ * Merge the required `sohl.archetype` frontmatter into a document's `flags`,
+ * returning a new object (the input is never mutated). A numeric archetype
+ * seeds `flags.sohl.docArchetype`; `null` omits the flag (and clears any stale
+ * `docArchetype` while preserving sibling `sohl` flags); an absent value
+ * throws. See {@link resolveArchetype}.
+ *
+ * @param {object} fm              Parsed frontmatter.
+ * @param {object} [flags]         The entry's existing flags (e.g. `fm.flags`).
+ * @param {string} label           Human-readable context for error messages.
+ * @returns {object}               The flags object with the archetype applied.
+ * @throws {Error} When `sohl.archetype` is absent or invalid.
+ */
+export function withArchetypeFlag(fm: object, flags?: object, label: string): object;
+/**
+ * Generates a compendium-source filename: `Name_id.json` with non-
+ * alphanumeric runs replaced by underscores.
+ */
+export function makeFilename(name: any, id: any): string;
+/**
+ * Standardize a name into a slug: lowercase, apostrophes removed,
+ * non-alphanumerics collapsed to single hyphens.
+ */
+/**
+ * Translate a content-relative image path into its Foundry-relative form.
+ *
+ * Content frontmatter (`img` / `portrait`) authors a single path that has to
+ * work for Foundry, the knowledgebase, and the website. For Foundry the bundled
+ * asset roots — `icons/...` and `images/...` — are served from the package
+ * directory, so they are rewritten to `<assetRoot>/<path>` — `systems/sohl/assets`
+ * for this repository, `modules/<id>/assets` for a module (#1508). Any other
+ * path (already package-rooted, an absolute URL) is returned unchanged, and an
+ * empty path yields `""`.
+ *
+ * This is translation only: the per-type default for an empty result is
+ * domain-specific (actors default differently from items, and gear differently
+ * again), so each compiler owns its own default and applies it to the result —
+ * `resolveImg(fm.img) || <default>`. For items that default is the art paired
+ * with the type's builder, reached through `itemArt()`, which runs the path
+ * back through this function so a registry entry and a note's `img:` are
+ * spelled the same way (#7).
+ *
+ * @param {string | null | undefined} raw - content-relative path from frontmatter.
+ * @param {{assetRoot: string}} [config] - The resolved build configuration.
+ *   Defaults to this repository's.
+ * @returns {string} the Foundry-relative path, or `""` when `raw` is empty.
+ */
+export function resolveImg(raw: string | null | undefined, config?: {
+    assetRoot: string;
+}): string;
+/**
+ * Resolves the display name from frontmatter, preferring `name.full`,
+ * falling back to `name` (if string), then `defaultValue`.
+ */
+export function resolveName(fm: any, defaultValue?: string): any;
+/**
+ * The oldest Foundry core this package supports, stamped into every compiled
+ * document as `_stats.coreVersion`.
+ *
+ * **Derived, never written twice.** `_stats.coreVersion` is what Foundry gates
+ * its migration shims on: a record stamped older than a shim is rewritten by it
+ * on load. Every pack once shipped `coreVersion: "14"`, which sorts *below*
+ * every v14 build and so left all shipped content permanently eligible for
+ * every v14 migration (#1533).
+ *
+ * **Read from the configuration, not from the shipped manifest.** It used to
+ * open `paths.packageManifest` and take `compatibility.minimum` out of it,
+ * because the configuration had no way to state the fact. Now that it does, the
+ * manifest is generated *from* the configuration — so reading it back would be
+ * a round trip through an artifact that need not exist yet: `build:db` can run
+ * before the manifest is written.
+ *
+ * Absent is a hard failure, not a default. A guessed floor is stamped into
+ * every document in the pack and stays invisible until something migrates on
+ * it, which is exactly why the manifest read threw rather than falling back.
+ *
+ * @param {{compatibility: {minimum: string}|null}} [config] - The resolved
+ *   configuration. Defaults to this repository's.
+ * @returns {string} The declared `compatibility.minimum`.
+ * @throws {Error} When the configuration declares no `compatibility.minimum`.
+ */
+export function supportedCoreVersion(config?: {
+    compatibility: {
+        minimum: string;
+    } | null;
+}): string;
+/**
+ * Default `_stats` block for compiled compendium entries.
+ *
+ * Every stamped identity is configuration (#1508): four compilers used to pass
+ * the same frozen `"0.6.0"` literal, and `systemId` / `lastModifiedBy` were
+ * written into this function. `coreVersion` alone is *not* configuration — it
+ * comes from {@link supportedCoreVersion}, the configured Foundry floor,
+ * so a document never claims to predate the migrations that would rewrite it.
+ *
+ * @param {string} [systemVersion] - The system version to stamp. Defaults to the
+ *   configured one.
+ * @param {{stats: {systemId: string, systemVersion: string,
+ *   lastModifiedBy: string}, paths: {packageManifest: string}}} [config] -
+ *   The resolved build configuration. Defaults to this repository's.
+ * @returns {object} The `_stats` block.
+ */
+export function buildStats(systemVersion?: string, config?: {
+    stats: {
+        systemId: string;
+        systemVersion: string;
+        lastModifiedBy: string;
+    };
+    paths: {
+        packageManifest: string;
+    };
+}): object;
+/**
+ * The `_stats` block every compiler stamps on an entry it emits, built once.
+ *
+ * Each compiler used to hoist `const STATS = buildStats()` at module scope,
+ * which read the shipped package manifest the moment the module was imported —
+ * so importing a compiler required a manifest to exist even when nothing was
+ * going to be compiled (#2). Deferred to first use and memoised here, the
+ * cost and the identity are what they always were; only the moment moved.
+ *
+ * @returns {object} The default `_stats` block, shared by every compiler.
+ */
+export function defaultStats(): object;
+/**
+ * Indexes **every** note in the content tree so any pack compiler can resolve a
+ * wikilink to any other document. Shared by all three compilers: a skill links
+ * to another skill, a journal to a creature, a creature to a rules page, and
+ * each target's own **type** decides which pack the UUID points into.
+ *
+ * Each note's pack is resolved here, once, and stored on its index entry: a
+ * UUID carries a pack name, so a repository shipping several packs of one type
+ * (#1566) would otherwise address every one of them as the first. A note whose
+ * declaration is unroutable is indexed against the conventional name and left
+ * for the compile pass to report — the index has no business failing a build,
+ * and the pass fails it with a far better message. The one exception is a
+ * **retired** content type (SoHL#1580): this walk is the first to see every
+ * note together with its path, and unlike an unroutable declaration there is
+ * no pass that would ever claim such a note and report it.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [router] - The pack router. Supplied by the calling pass so
+ *   the index and the compile agree about where each note landed; defaults to
+ *   this repository's own.
+ * @returns {{byShortcode: Map, byAlias: Map}} From `buildWikilinkIndex`.
+ */
+export function buildContentLinkIndex(contentBase: string, router?: object): {
+    byShortcode: Map<any, any>;
+    byAlias: Map<any, any>;
+};
+/**
+ * Converts the wikilinks in one note's markdown, reporting any that have no
+ * target in the content tree. Every compiler funnels through this so the
+ * diagnostic text and the leave-it-alone fallback are identical everywhere.
+ *
+ * Each report names the **file, line and column** the link sits on (#17), so
+ * it can be opened and fixed — and so two identical links on one note are
+ * tellable apart. That needs `file` and the note's `bodyLine` / `bodyColumn`;
+ * without them the diagnostic still reports, one field shorter, rather than
+ * inventing a position.
+ *
+ * @param {string} body - The note's markdown body, tables already expanded.
+ * @param {object} ctx - `{ type, id, pack, docPack, index, name }` — `name` is
+ *   used in the message, and the two pack names address a `[[#slug]]`
+ *   self-link, whose target is the source note itself and so has no index
+ *   entry. Position is carried by `{ file, bodyLine, bodyColumn, lineMap }`,
+ *   the last from {@link expandNoteTables}.
+ * @returns {{markdown: string, unresolved: Array<object>}}
+ * @throws {Error} On an ambiguous alias or a dead qualified address. The error
+ *   carries `file` and `position`, so a caller reports it in the same form
+ *   rather than re-deriving one.
+ */
+export function convertNoteWikilinks(body: string, { type, id, pack, docPack, index, name, file, bodyLine, bodyColumn, lineMap, }: object): {
+    markdown: string;
+    unresolved: Array<object>;
+};
+/**
+ * Every note in the content tree, in the shape the `dataview` table expander
+ * searches: its frontmatter plus where it sits in the tree. Ordered by path so
+ * a table that leaves rows tied still emits identically on every build.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @returns {Array<{fm: object, path: string, tld: string, folder: string,
+ *   absPath: string}>}
+ */
+export function collectContentDocs(contentBase: string): Array<{
+    fm: object;
+    path: string;
+    tld: string;
+    folder: string;
+    absPath: string;
+}>;
+/**
+ * Expand the fenced `dataview` tables in one note's markdown, before wikilinks
+ * are resolved — so a generated cell may itself be a wikilink.
+ *
+ * A table searches only notes of the source note's own `package`, so a SoHL
+ * page never tabulates setting-package content (and vice versa).
+ *
+ * @param {string} body - The note's markdown body.
+ * @param {object} ctx
+ * @param {Array<object>} ctx.docs - From {@link collectContentDocs}.
+ * @param {string} ctx.name - The note, for the error message.
+ * @param {string} [ctx.pkg] - The source note's `package`.
+ * @param {object} [ctx.fm] - The source note's frontmatter, which is what a
+ *   query's `this` reads. Its entry in `docs` supplies the path as well.
+ * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line,
+ *   so a failing directive can be reported at its position in the file.
+ * @returns {{markdown: string, lineMap: Array<{line: number,
+ *   generated: boolean}>}} The body with every table expanded, and where each
+ *   emitted line came from — which is what lets a diagnostic about the
+ *   expanded body name an authored position (#17).
+ * @throws {Error} When a query is malformed or unsupported — the note fails to
+ *   compile rather than shipping a table-shaped hole. The error carries
+ *   `position`, the directive's own line.
+ */
+export function expandNoteTables(body: string, { docs, name, pkg, fm, bodyLine }: {
+    docs: Array<object>;
+    name: string;
+    pkg?: string | undefined;
+    fm?: object | undefined;
+    bodyLine?: number | undefined;
+}): {
+    markdown: string;
+    lineMap: Array<{
+        line: number;
+        generated: boolean;
+    }>;
+};
+/**
+ * Loads a folders.yaml file as an array of folder entries. Returns []
+ * when the file is missing (logging a warning) so packs without folders
+ * can opt out simply by not committing the file.
+ */
+export function loadFolders(foldersFile: any): any[];
+/**
+ * Validates folder invariants and returns a resolver function that maps a
+ * folder id to the same id (after verifying it exists). Returns `null` for
+ * a null/empty input; throws for an unknown id.
+ *
+ * Invariants:
+ *   - Every folder must have a non-empty id
+ *   - Every folder must have a name
+ *   - Sibling folders (same parentFolderId) must have unique names
+ *   - Every parentFolderId must match an existing folder id (or be "")
+ *
+ * Returns { resolver, folders } where folders is the validated list.
+ */
+export function buildFolderResolver(folders: any): {
+    resolver: (folderId: any) => string | null;
+    folders: any;
+};
+/**
+ * Builds a compendium-source filename for a folder JSON document:
+ * `folder_Name_id.json` with non-alphanumeric runs replaced by
+ * underscores.
+ */
+export function folderFilename(name: any, id: any): string;
+/**
+ * Writes one JSON document per folder into `destDir`. `documentType`
+ * determines the folder's Foundry `type` field — `"Item"` for the items
+ * pack, `"JournalEntry"` for the journals pack.
+ */
+export function writeFolderDocs(folders: any, stats: any, destDir: any, documentType: any): void;
+export const md: any;
+export { slugify } from "./content-slug.mjs";
+export { makeId } from "./ids.mjs";
+export { getFrontmatter, sohlField, resolveCharges, resolveSkillAptitudes, resolveRelation, requireSubType, parseValueDesc } from "./frontmatter.mjs";

package/types/engine/ids.d.mts

@@ -0,0 +1,126 @@
+/**
+ * Stable 16-char hex id derived from `${namespace}:${value}`. Use for deriving
+ * page ids from heading text when no explicit id is supplied.
+ *
+ * @param {string} namespace - Keeps unrelated derivations from colliding.
+ * @param {string} value - The input the id is a function of.
+ * @returns {string} A 16-character hexadecimal Foundry id.
+ */
+export function makeId(namespace: string, value: string): string;
+/**
+ * Throw if `type` names a retired content type.
+ *
+ * @param {string} type - The note's declared `type`, or a link's qualifier.
+ * @param {string} [where] - What carries it — a file path, a link target —
+ *   appended to the message so the reader can go straight to it.
+ * @throws {Error} Naming the replacement type.
+ */
+export function assertTypeNotRetired(type: string, where?: string): void;
+/**
+ * The pack a type's documents live in, in the conventional one-pack-per-type
+ * layout.
+ *
+ * Item types are the open set — a new one is added whenever the system grows a
+ * document type — so they are the **default** rather than an enumerated list. A
+ * hand-maintained list is what made an entire content directory silently
+ * unlinkable once (#1276); nothing to maintain, nothing to forget.
+ *
+ * The `docType` is the authority: it is a property of the *content type* and
+ * holds however a repository names or splits its packs. The `pack` is the
+ * conventional name only — a repository may rename its packs, or ship several
+ * of one type (#1566), in which case the pack a particular note's document
+ * lands in comes from `engine/pack-router.mjs` and is passed to
+ * {@link compendiumUuid} explicitly. This module stays free of the
+ * configuration so the link resolver above it can stay pure.
+ *
+ * @param {string} type - The target note's `type`.
+ * @returns {{pack: string, docType: string}} The pack and document type.
+ * @throws {Error} If `type` names a retired content type — see
+ *   {@link RETIRED_TYPES}. The open-set default would otherwise route it to the
+ *   items pack and say nothing.
+ */
+export function packForType(type: string): {
+    pack: string;
+    docType: string;
+};
+/**
+ * A document's full compendium UUID.
+ *
+ * This is the one place a UUID is spelled. Every link is resolved by looking up
+ * an address computed here — never by concatenating a prefix at the point of
+ * use, which is how the package came to be hard-coded in two separate files.
+ *
+ * @param {string} packageId - The Foundry package that ships the pack, e.g.
+ *   `sohl`. A system id or a module id; Foundry addresses both the same way.
+ * @param {string} type - The note's content `type`.
+ * @param {string} id - The document's id.
+ * @param {string} [packName] - The pack the document actually landed in, from
+ *   the pack router. Supplied wherever the note is known, because a repository
+ *   may ship several packs of one type and a UUID carries the pack name
+ *   (#1566). Omitted only where there is no note to route — the conventional
+ *   name from {@link packForType} then stands in.
+ * @returns {string} `Compendium.<packageId>.<pack>.<DocumentType>.<id>`
+ */
+export function compendiumUuid(packageId: string, type: string, id: string, packName?: string): string;
+/**
+ * The UUID of a JournalEntry page.
+ *
+ * @param {string} entryUuid - The owning entry's UUID, from
+ *   {@link compendiumUuid}.
+ * @param {string} pageId - The page's id.
+ * @returns {string} The page's UUID.
+ */
+export function pageUuid(entryUuid: string, pageId: string): string;
+/**
+ * Every content type that compiles into a Foundry `Scene` — a **map note**
+ * (#1525). The three differ only in derived canvas defaults, which is the map
+ * compiler's business; everything else treats them alike.
+ *
+ * Declared in this leaf module because several passes that must not depend on
+ * the map compiler need it: the pack router below, and the doc-carrying type
+ * set in `item-docs.mjs` (a map note's prose becomes a JournalEntry, exactly as
+ * an item's or a macro's does).
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const MAP_TYPES: ReadonlySet<string>;
+/**
+ * Content type → the pack its documents compile into, and the document type
+ * that pack holds.
+ *
+ * These are pack **names**, not addresses. The package that owns the pack is
+ * supplied by the caller, because it is a property of the repository doing the
+ * building and not of the content: the same notes compiled by a different
+ * repository belong to a different package. Baking the package into these
+ * values is what made every link emitted by `sohl-thalorna` address the `sohl`
+ * system (#1498) — correct here only by coincidence.
+ *
+ * @type {Readonly<Record<string, {pack: string, docType: string}>>}
+ */
+export const PACK_BY_TYPE: Readonly<Record<string, {
+    pack: string;
+    docType: string;
+}>>;
+/**
+ * Content types that no longer exist, and what replaced each one.
+ *
+ * `character` and `creature` were retired in favour of the single `being` they
+ * had always compiled into (SoHL#1580). They are recorded here rather than
+ * simply deleted because deleting them is the one change that fails *quietly*:
+ * every type not named in {@link PACK_BY_TYPE} falls through to the open item
+ * set below, so a note or a link left on the old spelling would be routed to
+ * the items pack — a wrong answer, arrived at silently, which is exactly the
+ * failure mode the open-set default exists to avoid for real item types.
+ *
+ * Keeping the names lets {@link assertTypeNotRetired} say what happened and
+ * what to write instead. Entries stay for as long as content in the wild might
+ * still carry them.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const RETIRED_TYPES: Readonly<Record<string, string>>;
+/** Where every other content type compiles: the items pack. */
+export const ITEM_PACK: Readonly<{
+    pack: "items";
+    docType: "Item";
+}>;

package/types/engine/index.d.mts

@@ -0,0 +1,33 @@
+export * as ids from "./ids.mjs";
+export * as codeFences from "./code-fences.mjs";
+export * as frontmatter from "./frontmatter.mjs";
+export * as contentTree from "./content-tree.mjs";
+export * as packConfig from "./pack-config.mjs";
+export * as packRouter from "./pack-router.mjs";
+export * as contentPackage from "./content-package.mjs";
+export * as contentSlug from "./content-slug.mjs";
+export * as contentAddress from "./content-address.mjs";
+export * as foreignManifests from "./foreign-manifests.mjs";
+export * as kbManifest from "./kb-manifest.mjs";
+export * as manifestEmit from "./manifest-emit.mjs";
+export * as siteBuild from "./site-build.mjs";
+export * as contentLint from "./content-lint.mjs";
+export * as contentLinks from "./content-links.mjs";
+export * as webWikilinks from "./web-wikilinks.mjs";
+export * as contentTables from "./content-tables.mjs";
+export * as helpers from "./helpers.mjs";
+export * as itemRegistry from "./item-registry.mjs";
+export * as itemDocs from "./item-docs.mjs";
+export * as wikilinks from "./wikilinks.mjs";
+export * as wikilinkSyntax from "./wikilink-syntax.mjs";
+export * as siteIndex from "./site-index.mjs";
+export * as baseCompiler from "./base-compiler.mjs";
+export * as journals from "./journals.mjs";
+export * as macros from "./macros.mjs";
+export * as mapNotes from "./map-notes.mjs";
+export * as scenes from "./scenes.mjs";
+export * as sceneLevels from "./scene-levels.mjs";
+export * as generate from "./generate.mjs";
+export * as compendiums from "./compendiums.mjs";
+export * as regionEvents from "./region-events.mjs";
+export { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS, REGION_EVENT_TO_TRIGGER } from "./region-events.mjs";

package/types/engine/item-docs.d.mts

@@ -0,0 +1,73 @@
+/**
+ * Every content type whose **prose compiles into a JournalEntry of its own**,
+ * addressed by the virtual `doc<type>` qualifier.
+ *
+ * Every item type, plus `macro` — a macro note's body documents the script the
+ * note also compiles into a Macro (#1514), which is the same shape as an item
+ * and its description: one note, two documents, the prose living in the
+ * journals pack.
+ *
+ * **One set, read by the compiler and the emitter alike.** The journals pass
+ * decides what to compile from it, and the link manifest decides what to
+ * publish a `doc<type>` entry for. Held apart, the two drift into a manifest
+ * that asserts documentation nothing compiled — or a compiled entry no
+ * consumer can address. It is composed exactly once, in `defineConfig`, and
+ * read from there — never recomposed at a call site.
+ *
+ * `doc` notes and actors are absent: each is a single document, so it has no
+ * separate documentation to address.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2).
+ *
+ * @returns {ReadonlySet<string>} The configured doc-carrying types.
+ */
+export function docEntryTypes(): ReadonlySet<string>;
+/**
+ * Whether a content note's type is one whose prose becomes a JournalEntry of
+ * its own.
+ *
+ * @param {string} type - The note's `type` frontmatter.
+ * @returns {boolean} True for an item type, for `macro` and for a map type;
+ *   false for `doc` and for actors.
+ */
+export function hasDocEntry(type: string): boolean;
+/**
+ * The id of the JournalEntry a note's prose compiles into — an item's, or a
+ * macro's.
+ *
+ * Derived from the note's own id so that the pass writing the document and the
+ * pass writing its documentation agree without either reading the other's
+ * output. It is deliberately not the note's id itself: the two documents are
+ * distinct, live in different packs, and sharing an id would make either one's
+ * UUID ambiguous to read.
+ *
+ * The `"item-doc"` hash namespace is **frozen**: it is baked into every entry
+ * id already shipped, and every `@UUID` pointing at one. It names where the
+ * derivation started, not what may use it.
+ *
+ * @param {string} itemId - The note's `id` frontmatter.
+ * @returns {string} A 16-character Foundry id.
+ */
+export function itemDocEntryId(itemId: string): string;
+/**
+ * The description an item carries in place of its prose: a `@UUID` link to the
+ * first page of its item doc, and nothing else.
+ *
+ * "Nothing else" is the whole convention — a description that is *only* a link
+ * is a pointer, and anything alongside it would make it ordinary prose that
+ * happens to contain a link, which the runtime would then show verbatim.
+ *
+ * @param {string} packageId - The Foundry package shipping the journals pack.
+ *   Supplied rather than assumed (#1498).
+ * @param {string} itemId - The item note's `id` frontmatter.
+ * @param {string} name - The item's name, used as the link's label. It shows
+ *   only if the target ever fails to resolve, where a broken link naming the
+ *   item beats a bare UUID.
+ * @param {string} firstPageId - The id of the entry's first page, from
+ *   {@link journalPageId}.
+ * @returns {string} The pointer to store in `system.docHtml`.
+ */
+export function itemDocPointer(packageId: string, itemId: string, name: string, firstPageId: string): string;
+export { itemTypes };
+import { itemTypes } from "./item-registry.mjs";

package/types/engine/item-registry.d.mts

@@ -0,0 +1,57 @@
+/**
+ * Every content type that compiles into an item — and therefore into an item
+ * doc. Read by the Item compiler to know what to claim, and by the journals
+ * pass to know whose prose it is holding.
+ *
+ * **Derived, never authored.** These are the keys of the consuming
+ * repository's `itemBuilders` registry, so the whitelist and the builder table
+ * are the same list and cannot drift apart. They already had: `trait` was
+ * whitelisted long after the item type was retired (#651), with no builder
+ * behind it, so every `type: trait` note passed the gate and then failed to
+ * compile (#1504).
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2).
+ *
+ * @returns {ReadonlySet<string>} The configured item types.
+ */
+export function itemTypes(): ReadonlySet<string>;
+/**
+ * The builder the consuming repository registered for an item type.
+ *
+ * Unreachable through the compiler — its whitelist *is* this registry's keys —
+ * so a throw here means a caller invented a type. It names the type rather than
+ * failing as an anonymous `is not a function` (#1504).
+ *
+ * @param {string} type - The note's `type` frontmatter.
+ * @returns {(fm: object) => object} The builder for that type.
+ * @throws {Error} When the configuration registers no builder for `type`.
+ */
+export function itemBuilder(type: string): (fm: object) => object;
+/**
+ * The default art for an item type — the image a note of that type is given
+ * when it carries no `img:` of its own.
+ *
+ * Read from the consuming repository's `itemBuilders` registry, the same place
+ * the type itself is declared, so a consumer's own type can bring art a
+ * SoHL-owned table could never hold. Art used to be looked up in
+ * `sohl/default-item-art.mjs` instead: a type was configurable while its
+ * default art was not, so a second consumer's items compiled only if every one
+ * of its notes set `img:` (#7).
+ *
+ * **Still fail-fast.** A type with neither a note-level `img:` nor paired art
+ * aborts the pack build rather than shipping a mismatched icon — the contract
+ * `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.
+ *
+ * @param {string} type - the item type.
+ * @returns {string} The default image path for that type.
+ * @throws {Error} When the type's registry entry pairs no `img`.
+ */
+export function itemArt(type: string): string;