@heroiclands/package-build 20.0.0 → 20.2.0

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

@@ -0,0 +1,127 @@
+/**
+ * Tier 1 — the letters, and the two whitespace characters a file is made of.
+ *
+ * The Latin-1 range is split around `U+00D7` and `U+00F7` deliberately: `×` and
+ * `÷` sit inside the letter block but are operators, and they are admitted
+ * below in Tier 3 on their own merits rather than smuggled in as letters.
+ *
+ * @param {number} cp - A Unicode code point.
+ * @returns {boolean} Whether Tier 1 admits it.
+ */
+export function isLetterTier(cp: number): boolean;
+/**
+ * Whether the charset admits a code point anywhere in a note.
+ *
+ * @param {number} cp - A Unicode code point.
+ * @returns {boolean} Whether it is allowed outside a code fence.
+ */
+export function isAllowedCodePoint(cp: number): boolean;
+/**
+ * Whether a code point is diagram furniture, admitted inside a fence only.
+ *
+ * A fenced block is set in the mono face, and the mono face is not the book
+ * face — so the question "does the text font have this" is the wrong question
+ * to ask about a character in an ASCII-art org chart. All three ranges were
+ * confirmed present in DejaVu Sans Mono, the mono face Typst embeds.
+ *
+ * @param {number} cp - A Unicode code point.
+ * @returns {boolean} Whether a fence may carry it.
+ */
+export function isDiagramCodePoint(cp: number): boolean;
+/**
+ * The reason a code point is refused.
+ *
+ * @param {number} cp - A Unicode code point.
+ * @returns {string} A clause naming what it is and what to do instead.
+ */
+export function refusalFor(cp: number): string;
+/**
+ * Every non-NFC run in a string, with the composed form it should have been.
+ *
+ * Reported as **runs** rather than as bare combining marks, because `y` plus
+ * `U+0301` is one authoring mistake and pointing at the accent alone would name
+ * the half the author did not type.
+ *
+ * @param {string} text - File contents.
+ * @returns {Array<{sequence: string, composed: string, index: number}>} Each
+ *   offending run, in the order it appears.
+ */
+export function decomposedRuns(text: string): Array<{
+    sequence: string;
+    composed: string;
+    index: number;
+}>;
+/**
+ * Check one file's text against the charset and the normalization rule.
+ *
+ * Findings are **deduplicated per character per line**: a 60-cell table of
+ * `━` is one mistake made once, and sixty findings would bury the other
+ * fifty-nine things wrong with the tree.
+ *
+ * @param {string} text - The file's contents.
+ * @param {string} file - Path to report, relative to the tree.
+ * @returns {Array<{file: string, line: number, column: number,
+ *   severity: "error", message: string}>} What is wrong, in file order.
+ */
+export function checkText(text: string, file: string): Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "error";
+    message: string;
+}>;
+/**
+ * Walk a content tree and check every authored file in it.
+ *
+ * Dot-directories are skipped: `.obsidian` carries editor state, and a plugin
+ * manifest's CRLF line endings are not this tree's prose. That is not a
+ * theoretical exclusion — it was the first thing a run over `sohl-thalorna`
+ * reported before the skip existed.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore
+ *   in addition to the dot-directories always skipped.
+ * @param {readonly string[]} [opts.extensions] - File extensions to read.
+ * @returns {{findings: Array<{file: string, line: number, column: number,
+ *   severity: "error", message: string}>, files: number}} The findings, and how
+ *   many files produced them.
+ */
+export function lintContentCharset(contentBase: string, { skipDirectories, extensions }?: {
+    skipDirectories?: readonly string[] | undefined;
+    extensions?: readonly string[] | undefined;
+}): {
+    findings: Array<{
+        file: string;
+        line: number;
+        column: number;
+        severity: "error";
+        message: string;
+    }>;
+    files: number;
+};
+/**
+ * Tier 2 — typography, enumerated one codepoint at a time.
+ *
+ * **Not the General Punctuation block.** `U+2000`–`U+206F` carries `U+200B`
+ * ZERO WIDTH SPACE, the `U+200E`/`U+200F` direction marks, the `U+2028`/`U+2029`
+ * separators, the `U+202A`–`U+202E` bidi overrides and `U+2060` WORD JOINER —
+ * precisely the invisibles this charset exists to refuse. Admitting the block
+ * to reach the em dash would admit all of them, so the ten that are wanted are
+ * named and the block is not.
+ *
+ * @type {ReadonlySet<number>}
+ */
+export const TYPOGRAPHY: ReadonlySet<number>;
+/**
+ * Tier 3 — the notation the rules and price tables are written in.
+ *
+ * Every one of these is carried by seven or eight of the eight probed faces, so
+ * the tier costs nothing in font freedom. It is a separate tier from the
+ * typography above only because it is a separate argument: these earn their
+ * place by being *needed* — a Shock threshold reads `≥ 10`, a wall is `10′ ×
+ * 11′` — where the typography earns it by being unavoidable.
+ *
+ * @type {ReadonlySet<number>}
+ */
+export const NOTATION: ReadonlySet<number>;

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

@@ -0,0 +1,151 @@
+/**
+ * Look one name up.
+ *
+ * @param {string} name - The name written between the colons, without `icon-`.
+ * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * @returns {{style: string, icon: string, label: string}|null} The entry, or
+ *   `null` when the registry does not declare it.
+ */
+export function resolveIcon(name: string, registry?: Record<string, object>): {
+    style: string;
+    icon: string;
+    label: string;
+} | null;
+/**
+ * The HTML the journals and the website emit — what the system already renders.
+ *
+ * Carries an accessible name rather than `aria-hidden`. The system's own
+ * templates hide their icons because a labelled parent element speaks for them;
+ * an icon dropped into a sentence has no such parent, and "the ☆ toggles it"
+ * read aloud as "the toggles it" is a sentence with a hole in it.
+ *
+ * @param {{style: string, icon: string, label: string}} entry - A registry entry.
+ * @returns {string} An `<i>` element.
+ */
+export function iconHtml(entry: {
+    style: string;
+    icon: string;
+    label: string;
+}): string;
+/**
+ * Every icon a string names, in the order written.
+ *
+ * @param {string} text - Markdown source.
+ * @returns {Array<{name: string, index: number, raw: string}>} What it names.
+ */
+export function iconsIn(text: string): Array<{
+    name: string;
+    index: number;
+    raw: string;
+}>;
+/**
+ * Report every icon a tree names that its registry does not declare.
+ *
+ * The whole point of a registry is that a typo is answerable, so this is the
+ * half that makes `:icon-stra:` a finding rather than three words of literal
+ * text nobody notices in a rendered page.
+ *
+ * @param {string} text - The file's contents.
+ * @param {string} file - Path to report.
+ * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * @returns {Array<{file: string, line: number, column: number,
+ *   severity: "error", message: string}>} The unknown names.
+ */
+export function lintIcons(text: string, file: string, registry?: Record<string, object>): Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: "error";
+    message: string;
+}>;
+/**
+ * Refuse a registry that names a style Font Awesome Free does not ship.
+ *
+ * @param {Record<string, object>} registry - A package's icon table.
+ * @param {string} [where="icons"] - Where to say the fault is.
+ * @returns {Array<{severity: "error", message: string}>} What is wrong with it.
+ */
+export function checkIconRegistry(registry: Record<string, object>, where?: string): Array<{
+    severity: "error";
+    message: string;
+}>;
+/**
+ * Walk a content tree and report every icon name its registry does not declare.
+ *
+ * Its own walk rather than the charset check's, so both modules stay leaves
+ * with nothing imported between them. The cost is one extra pass over the tree,
+ * which is the cheaper half of a lint that already parses every note.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
+ * @param {Record<string, object>} [opts.registry] - The package's icon table.
+ * @returns {{findings: Array<{file: string, line: number, column: number,
+ *   severity: "error", message: string}>, files: number}} What it found.
+ */
+export function lintContentIcons(contentBase: string, { skipDirectories, registry }?: {
+    skipDirectories?: readonly string[] | undefined;
+    registry?: Record<string, object> | undefined;
+}): {
+    findings: Array<{
+        file: string;
+        line: number;
+        column: number;
+        severity: "error";
+        message: string;
+    }>;
+    files: number;
+};
+/**
+ * A markdown-it plugin rendering `:icon-name:` inline.
+ *
+ * An unknown name is left **exactly as written** rather than dropped. The name
+ * is reported by {@link lintIcons}, and a rendered page that still shows
+ * `:icon-stra:` is how the author finds it without reading a log.
+ *
+ * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * @returns {(md: object) => void} A markdown-it plugin.
+ */
+export function iconPlugin(registry?: Record<string, object>): (md: object) => void;
+/**
+ * The Font Awesome styles a registry entry may name.
+ *
+ * Free ships these three and no others, so a `light` or `duotone` entry would
+ * name a glyph the shipped font does not contain — refused here rather than
+ * discovered as a blank space in a printed book.
+ *
+ * @type {readonly string[]}
+ */
+export const ICON_STYLES: readonly string[];
+/**
+ * The icons the user guide already depicts, under the names it should call them.
+ *
+ * Each entry was read off the interface it describes rather than invented: the
+ * `star`/`star-outline` pair is the filled and hollow star the mastery row and
+ * the improve flag draw, and `edit` is the pencil the formula editor opens
+ * from. The names are what a *writer* would reach for — `delete`, not
+ * `trash-can` — because the writer is the one typing them; the Font Awesome
+ * spelling is this table's business, not theirs.
+ *
+ * @type {Readonly<Record<string, {style: string, icon: string, label: string}>>}
+ */
+export const DEFAULT_ICONS: Readonly<Record<string, {
+    style: string;
+    icon: string;
+    label: string;
+}>>;
+/**
+ * The shape a note writes, and the one this module claims.
+ *
+ * The `icon-` prefix is what keeps it out of the way of an emoji shortcode: a
+ * surface that also renders `:smile:` can tell the two apart without a lookup,
+ * and a reader can tell what `:icon-star:` is without knowing this module
+ * exists. Names are lowercase, digits and hyphens — the charset an address
+ * segment already uses (#59), so nothing new has to be explained.
+ *
+ * Not `:name[content]`. That is remark-directive syntax, and this toolchain
+ * parses with markdown-it; a directive would render as its own literal text.
+ *
+ * @type {RegExp}
+ */
+export const ICON_PATTERN: RegExp;

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

@@ -32,6 +32,25 @@ export function catalogDir(config: object, id: string, version: string): string;
  * @returns {string} The path, whether or not it exists.
  */
 export function cachedSchemaPath(config: object, id: string, version: string): string;
+/**
+ * What to record about the packs being extracted.
+ *
+ * Exported so the pair is one fact: {@link foreignItemCatalogDirs} reads what
+ * this writes, and a test that hand-wrote the file would prove the reader
+ * against a transcription of the format rather than against the format.
+ *
+ * A pack declaring no `system` records `null` — Foundry requires the field on
+ * an Item pack, so this is the shape of a manifest that is wrong rather than a
+ * case with a meaning, and `null` reads as "neutral", which is the safe way to
+ * be wrong: a neutral pack is read by every system rather than by none.
+ *
+ * @param {readonly object[]} itemPacks - The manifest's Item pack entries.
+ * @returns {Array<{name: string, system: string|null}>} What each one is.
+ */
+export function itemPackManifest(itemPacks: readonly object[]): Array<{
+    name: string;
+    system: string | null;
+}>;
 /**
  * Write an unzipped archive's entries under `dest`.
  *
@@ -159,10 +178,27 @@ export function fetchAllCatalogs(config: object): Promise<number>;
  * Reads the cache only. A cold cache is an error naming the command that fills
  * it, rather than a download nobody asked for.
  *
+ * **Scoped to one system when the caller compiles for one (#58)**, exactly as
+ * {@link module:engine/generate.itemPackJsonDirs} scopes the local half. The
+ * two halves answer the same lookup — `loadItemsMap` merges them into one
+ * address space keyed by `subType:shortcode` — so scoping only the local one
+ * leaves the collision it was meant to remove: `skill:awar` is a real address
+ * in both vocabularies, and a `harn-ensemble` actor compiled for `hm3` would
+ * resolve three quarters of its references against whichever document the
+ * dependency's `sohl` pack happened to supply. A pack that declares no system
+ * is neutral and always read; asking for no system reads every pack, which is
+ * every single-system build.
+ *
  * @param {object} config - The resolved build configuration.
- * @returns {string[]} Every cached dependency's item directories.
+ * @param {string|null} [system] - The system the caller is compiling for.
+ *   Omitted or `null`, every cached pack is read.
+ * @returns {Array<{dir: string, package: string}>} Every cached dependency's
+ *   item directories, each with the package that published it.
  */
-export function foreignItemCatalogDirs(config: object): string[];
+export function foreignItemCatalogDirs(config: object, system?: string | null): Array<{
+    dir: string;
+    package: string;
+}>;
 /**
  * The file a system publishes its `system` field sets as (#60).
  *

package/types/engine/frontmatter-lint.d.mts

@@ -1,3 +1,97 @@
+/**
+ * What one system block accepts beyond the keys every block carries.
+ *
+ * @typedef {object} SystemBlockSpec
+ * @property {readonly string[]} [known] - Keys stated outright.
+ * @property {boolean} [fieldVocabulary] - Whether the note type's declared field
+ *   names, as the caller's `schemas` state them, are keys of this block.
+ * @property {Readonly<Record<string, readonly object[]>>} [fields] - Type → this
+ *   system's own declared fields. A type it does not name is a type this system
+ *   says nothing about, and its block is left unchecked on such a note rather
+ *   than reported wholesale.
+ */
+/**
+ * Every system a configuration says its tree carries (#58).
+ *
+ * **Which systems a package ships for is already declared**, in three places
+ * that answer different questions, so this reads all three rather than asking a
+ * new one:
+ *
+ * - `systems:` (#48) declares them without requiring one, which is how a
+ *   package ships for several;
+ * - a **pack's** `system:` is the same statement made per pack, and it is the
+ *   one some trees make: `harn-ensemble` declares an `actors-sohl` and an
+ *   `actors-hm3` and nothing else about either system. It is already
+ *   authoritative elsewhere — `eligibleFor` fails a note for want of the block
+ *   a pack's `system:` names — so a lint that did not read it would refuse a
+ *   note at compile for a block it never checked;
+ * - `stats.systemId` is the package-wide answer where there is one, and it has
+ *   already absorbed every way of spelling that: a system package is its own
+ *   system, and a module takes `requiresSystem`, its lone `systems:` entry, or
+ *   its lone system relationship.
+ *
+ * A package naming a system in none of them is system-agnostic on purpose — its
+ * packs are core document types carrying no system data — so it carries no
+ * system block and naming one would invent it.
+ *
+ * @param {object} [config] - A resolved configuration from `defineConfig`.
+ * @returns {string[]} The system ids, deduplicated, in declared order.
+ */
+export function declaredSystems(config?: object): string[];
+/**
+ * The system blocks a configuration says its tree carries, and what each
+ * accepts (#58).
+ *
+ * The lint checks the blocks its caller names, and for as long as there was one
+ * system the only caller named none — so every tree took the `sohl:` of
+ * {@link DEFAULT_SYSTEM_BLOCKS}, a constant, in a module whose whole discipline
+ * is that it states no vocabulary of its own. That is wrong in both directions
+ * the moment a second system exists, and the second direction is the worse:
+ *
+ * - a package shipping for `hm3` had its `hm3:` block **never looked at**, so
+ *   every key in it was discarded at compile without a word — the silent-drop
+ *   family this check exists to close;
+ * - and the block that *was* checked was named after a system that package does
+ *   not ship for, so the one finding it could make was about nothing.
+ *
+ * **A block's vocabulary has two sources, and a system may have both.**
+ *
+ * - The **note schemas** the caller hands in as `schemas`. Those belong to one
+ *   system — the CLI imports `sohl/note-schemas.mjs` — and `schemaSystem` is the
+ *   caller naming which, because only the caller knows. It is the only source
+ *   that reaches a type no item registry declares, which is to say `being`: the
+ *   2,512 notes `harn-ensemble` is made of, and the reason this is not an
+ *   optional refinement.
+ * - The system's **own registry**, `itemFieldsBySystem`, keyed by system and
+ *   until now read by nothing. This is what a *second* system's block is held
+ *   to, since the note schemas describe its neighbour.
+ *
+ * A system with neither is left out: nothing can state what its block may
+ * carry, and holding it to an empty vocabulary would report every key in a
+ * correct tree. **That is a check that does not run**, which is
+ * indistinguishable from one that passed, so the caller says it out loud —
+ * {@link declaredSystems} is the other half of that comparison. `harn-ensemble`
+ * is the tree it names: two systems, and an `itemBuilders` registry for
+ * neither, so its `hm3:` block is unchecked until it declares one.
+ *
+ * An earlier draft of this took the note schemas for a system's vocabulary only
+ * where the package declared **one** system, on the reasoning that with several
+ * there is nothing to say which one they describe. There is: the caller, which
+ * chose them. The guess cost `harn-ensemble` its whole `sohl:` check — two
+ * systems declared, so the fallback never fired — which is the coverage this
+ * change exists to widen rather than narrow.
+ *
+ * @param {object} [config] - A resolved configuration from `defineConfig`.
+ * @param {object} [options] - Options.
+ * @param {string} [options.schemaSystem] - The system whose vocabulary the
+ *   caller's `schemas` state. There are two systems, not an open set, so this is
+ *   one word from the caller rather than a mechanism.
+ * @returns {Readonly<Record<string, SystemBlockSpec>>} The blocks to check, in
+ *   declared order. A system nothing states the vocabulary of is absent.
+ */
+export function systemBlocksFor(config?: object, { schemaSystem }?: {
+    schemaSystem?: string | undefined;
+}): Readonly<Record<string, SystemBlockSpec>>;
 /**
  * Whether a value satisfies a declared {@link FieldSpec.kind}.
  *
@@ -32,9 +126,11 @@ export function matchesKind(value: unknown, kind: string): boolean;
  *   Supplied by the caller like `schemas`, so this module states no list of
  *   iconless types of its own; absent it, an inert `img:` goes unreported
  *   rather than every note's being (#349).
- * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
- *   The system blocks to check, and what each accepts. See
- *   {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {Readonly<Record<string, SystemBlockSpec>>} [opts.systems]
+ *   The system blocks to check, and what each accepts. Supplied by the caller
+ *   for the same reason `schemas` is — a build derives them from its
+ *   configuration through {@link systemBlocksFor}, and this module states no
+ *   system name of its own. See {@link DEFAULT_SYSTEM_BLOCKS} for the fallback.
  * @param {readonly string[]} [opts.packs] - The pack names this package
  *   declares, for a `data:` field whose map is keyed by pack. Supplied by the
  *   caller like `schemas` and `vocabulary`, and absent it no claim is made
@@ -49,10 +145,7 @@ export function lintNote(note: object, { schemas, index, vocabulary, packs, emit
         document: string | null;
         art: readonly string[];
     } | null) | undefined;
-    systems?: Readonly<Record<string, {
-        known?: readonly string[];
-        fieldVocabulary?: boolean;
-    }>> | undefined;
+    systems?: Readonly<Record<string, SystemBlockSpec>> | undefined;
     packs?: readonly string[] | undefined;
 }): object[];
 /**
@@ -64,8 +157,9 @@ export function lintNote(note: object, { schemas, index, vocabulary, packs, emit
  * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
  *   it declares (#128); see {@link lintNote}.
  * @param {boolean} [opts.references=true] - Whether to check references.
- * @param {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>} [opts.systems]
- *   The system blocks to check. See {@link DEFAULT_SYSTEM_BLOCKS}.
+ * @param {Readonly<Record<string, SystemBlockSpec>>} [opts.systems]
+ *   The system blocks to check; see {@link lintNote} and
+ *   {@link systemBlocksFor}.
  * @param {readonly string[]} [opts.packs] - The declared pack names; see
  *   {@link lintNote}.
  * @param {(type: string) => {document: string|null, art: readonly string[]}|null} [opts.emittedArt]
@@ -77,10 +171,7 @@ export function lintFrontmatter(index: object, { schemas, vocabulary, packs, emi
     schemas: Record<string, readonly object[]>;
     vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
-    systems?: Readonly<Record<string, {
-        known?: readonly string[];
-        fieldVocabulary?: boolean;
-    }>> | undefined;
+    systems?: Readonly<Record<string, SystemBlockSpec>> | undefined;
     packs?: readonly string[] | undefined;
     emittedArt?: ((type: string) => {
         document: string | null;
@@ -123,21 +214,48 @@ export const UNIVERSAL_KEYS: ReadonlySet<string>;
  * The system blocks a build checks, and what each accepts beyond the shared
  * vocabulary.
  *
- * One entry, because one system is what every existing tree declares — and the
- * default is a *declaration*, not a hard-coded assumption: a build that ships
- * content for two systems passes both, and each block is then checked against
- * its own vocabulary rather than against the other's (#58). A block nothing
- * declares is not checked, because nothing can say what it may carry, and
- * inventing a rule for it would report a correct tree red.
+ * One entry, because one system is what every existing tree declares — and it
+ * is a *fallback*, not the rule. {@link systemBlocksFor} derives the map from
+ * the configuration, which is what makes the block a package actually ships for
+ * the block that gets checked; this is what a caller holding no configuration
+ * gets, which in practice is a unit test.
  *
- * `fieldVocabulary` says the note type's own declared field names are keys of
- * this block. True for `sohl` and untrue in general: those names come from the
- * `itemBuilders` registry that this system declares, and a second system's
- * notes write a second system's fields.
+ * A block nothing declares is not checked, because nothing can say what it may
+ * carry, and inventing a rule for it would report a correct tree red.
  *
- * @type {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>}
+ * Three ways a block may state its vocabulary, and a spec declares at most one:
+ *
+ * - `known` — an explicit list of keys, for a caller stating them outright.
+ * - `fieldVocabulary` — the note type's own declared field names, as the
+ *   caller's `schemas` state them, are keys of this block. That holds for the
+ *   **one** system a single-registry tree ships for, where `schemas` *is* that
+ *   system's vocabulary, and in general holds for no other.
+ * - `fields` — type → that system's own declared fields, from the registry the
+ *   system declares. What a second system's block is checked against, because a
+ *   second system's notes write a second system's fields and the note-type
+ *   schemas describe somebody else's.
+ *
+ * @type {Readonly<Record<string, SystemBlockSpec>>}
  */
-export const DEFAULT_SYSTEM_BLOCKS: Readonly<Record<string, {
-    known?: readonly string[];
-    fieldVocabulary?: boolean;
-}>>;
+export const DEFAULT_SYSTEM_BLOCKS: Readonly<Record<string, SystemBlockSpec>>;
+/**
+ * What one system block accepts beyond the keys every block carries.
+ */
+export type SystemBlockSpec = {
+    /**
+     * - Keys stated outright.
+     */
+    known?: readonly string[] | undefined;
+    /**
+     * - Whether the note type's declared field
+     * names, as the caller's `schemas` state them, are keys of this block.
+     */
+    fieldVocabulary?: boolean | undefined;
+    /**
+     * - Type → this
+     * system's own declared fields. A type it does not name is a type this system
+     * says nothing about, and its block is left unchecked on such a note rather
+     * than reported wholesale.
+     */
+    fields?: Readonly<Record<string, readonly object[]>> | undefined;
+};

package/types/engine/helpers.d.mts

@@ -462,6 +462,14 @@ export function expandNoteTables(body: string, { docs, name, fm, bodyLine, sqlTa
  * underscores.
  */
 export function folderFilename(name: any, id: any): string;
+/**
+ * The markdown renderer every surface shares.
+ *
+ * `html: true` is long-standing and load-bearing — notes carry raw blocks — and
+ * it is also why {@link module:engine/content-icons} exists rather than an
+ * instruction to write `<i class="fa-solid …">` by hand: that would render on
+ * the two HTML surfaces and be silently dropped by the third (#378).
+ */
 export const md: import("markdown-it").MarkdownIt;
 export { slugify } from "./content-slug.mjs";
 export { makeId } from "./ids.mjs";

package/types/engine/index.d.mts

@@ -25,6 +25,8 @@ export * as foundryEntries from "./foundry-entries.mjs";
 export * as contentIndex from "./content-index.mjs";
 export * as siteBuild from "./site-build.mjs";
 export * as contentLint from "./content-lint.mjs";
+export * as contentCharset from "./content-charset.mjs";
+export * as contentIcons from "./content-icons.mjs";
 export * as contentLinks from "./content-links.mjs";
 export * as webWikilinks from "./web-wikilinks.mjs";
 export * as contentTables from "./content-tables.mjs";

package/types/engine/note-claims.d.mts

@@ -15,6 +15,59 @@
  * @returns {ReadonlySet<string>} The note types such a pass would claim.
  */
 export function noteTypesClaimedBy(docType: string, sources?: ClaimSources): ReadonlySet<string>;
+/**
+ * Every document class a note of one type compiles into (#152).
+ *
+ * **A note produces more than one document, and that is the ordinary case.** An
+ * item note compiles an Item *and* the JournalEntry its prose becomes; a map
+ * note a Scene and a JournalEntry; since #337 an actor note an Actor and a
+ * JournalEntry too. {@link claimedNoteTypes} unions over the configured packs
+ * and so answers "is this note compiled *at all*", which is #146's question and
+ * cannot see a note that compiles one of its two documents and loses the other.
+ *
+ * Asked of the **claim table** rather than of a list of its own, so the set of
+ * documents a type produces and the set of passes that claim it are one
+ * statement. A pass that starts claiming a type starts producing its document
+ * here, with nothing to remember.
+ *
+ * **Union across systems, never per system.** A type one system maps and
+ * another does not appears once, because the `Item` and `Actor` rows already
+ * fold the maps together — so this cannot report a document class a system
+ * deliberately declines to produce, which is the silence #79 requires.
+ *
+ * ## The JournalEntry row is the one that is per *note*
+ *
+ * Every other row is a property of the type: a `macro` note produces a Macro, a
+ * map note a Scene, whatever either says. Documentation is not. `Journals`
+ * declines a doc-carrying note whose body is empty — *"an item with no prose
+ * gets no doc, and the items pass leaves its description empty rather than
+ * pointing at nothing"* — so whether an item note produces a JournalEntry is
+ * decided by the note, not by its type.
+ *
+ * That distinction is the whole difference between a useful finding and a
+ * useless one. `sohl-kethira-basic` declares no JournalEntry pack and ships 393
+ * notes whose descriptions are *deliberately* empty, under the Fan Material
+ * Guidelines its configuration explains at length. A type-level answer would
+ * report every one of them for losing a document none of them produces. Asking
+ * per note, it reports none, and still reports `harn-ensemble`'s 2,517 beings,
+ * whose `{#appearance}` and `{#dossier}` prose is real and is lost.
+ *
+ * `hasProse` is therefore how the caller answers that, and it is a **thunk** so
+ * that the file is read only where the answer could change the outcome. Omitted,
+ * the answer is the type's full potential — every document such a note *could*
+ * produce — which is what a caller asking about a type rather than a note wants.
+ *
+ * @param {string} type - The note's declared `type`, current spelling.
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @param {object} [opts] - Options.
+ * @param {(() => boolean)|boolean} [opts.hasProse] - Whether *this note* carries
+ *   a body. Omitted, the type's potential is reported.
+ * @returns {string[]} The document classes, in {@link CLAIMABLE_DOCUMENT_TYPES}
+ *   order. Empty for a type nothing compiles.
+ */
+export function documentClassesFor(type: string, sources?: ClaimSources, { hasProse }?: {
+    hasProse?: boolean | (() => boolean) | undefined;
+}): string[];
 /**
  * Every note type some pack in a configuration would compile.
  *
@@ -133,6 +186,20 @@ export const UNIMPLEMENTED_TYPES: ReadonlySet<string>;
  */
 export const DERIVED_PACKED_TYPES: ReadonlySet<string>;
 export { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+/**
+ * Every Foundry document class {@link noteTypesClaimedBy} answers for.
+ *
+ * The switch above, read the other way round. It is written out rather than
+ * derived because a `switch` cannot be enumerated — and
+ * `tests/unclaimed-note-types.test.ts` holds the two together by checking that
+ * no class outside this list claims anything, so a row added there and not here
+ * fails rather than going quiet.
+ *
+ * Order is the order a reader meets them in a message, not a precedence.
+ *
+ * @type {readonly string[]}
+ */
+export const CLAIMABLE_DOCUMENT_TYPES: readonly string[];
 /**
  * What a claim question is asked against.
  *