@heroiclands/package-build 9.0.0 → 10.0.1

package/types/engine/field-spec.d.mts

@@ -1,31 +1,37 @@
-/**
- * Write `value` at a dotted path, creating the intermediate objects.
- *
- * Insertion order is the emitted JSON's key order, so a declaration's order is
- * the compiled document's order — which is what lets a field list replace a
- * hand-written object literal without changing a single byte of output.
- *
- * @param {object} target - The object to write into (mutated).
- * @param {string} dotted - Path, e.g. `"locations.flexible"`.
- * @param {any} value - The value to set.
- * @returns {object} `target`, for chaining.
- */
-export function setPath(target: object, dotted: string, value: any): object;
 /**
  * Read one declared field out of a note's frontmatter.
  *
+ * The *position* is resolved by {@link resolveFieldValue} — `<system>.system`
+ * first, then the legacy in-block key, then the declared shared source, then
+ * the default (#58). The **coercion** is applied here, once, wherever the value
+ * came from: a field's `read` is a statement about the field, not about where
+ * an author happened to write it, so `weight: "7"` reads as `7` at every one of
+ * those positions.
+ *
  * @param {FieldSpec} field - The declaration.
  * @param {object} fm - The note's frontmatter.
+ * @param {object} [options] - Options.
+ * @param {string} [options.block="sohl"] - Which system's block to resolve
+ *   against. The default is the one block every existing tree authors; a
+ *   second system passes its own.
  * @returns {any} The value to emit.
  */
-export function readField(field: FieldSpec, fm: object): any;
+export function readField(field: FieldSpec, fm: object, { block }?: {
+    block?: string | undefined;
+}): any;
 /**
  * Turn a field declaration into the builder it declares.
  *
  * @param {readonly FieldSpec[]} fields - The declaration, in emission order.
+ * @param {object} [options] - Options.
+ * @param {string} [options.block="sohl"] - Which system's block the builder
+ *   reads. One declaration compiles against any block, which is what lets two
+ *   systems declare the same shared source and different destinations.
  * @returns {(fm: object) => object} A `system`-block builder.
  */
-export function buildFromFields(fields: readonly FieldSpec[]): (fm: object) => object;
+export function buildFromFields(fields: readonly FieldSpec[], { block }?: {
+    block?: string | undefined;
+}): (fm: object) => object;
 /**
  * The fields of a declaration an author actually writes.
  *
@@ -38,12 +44,25 @@ export function buildFromFields(fields: readonly FieldSpec[]): (fm: object) => o
  * @returns {FieldSpec[]} Only the fields with a frontmatter `name`.
  */
 export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
+export { setPath };
 /**
  * @typedef {object} FieldSpec
- * @property {string} to - Dotted path in the emitted `system` block.
- * @property {string} [name] - Frontmatter key under `sohl:`, dotted for a
- *   nested one (`impact.die`). Absent means the value is not authored — see
- *   `value`.
+ * @property {string} to - Dotted path in the emitted `system` block — and,
+ *   since #58, the path a note authors the field at directly:
+ *   `<system>.system.<to>`.
+ * @property {string} [name] - The **shared, top-level property this field draws
+ *   from** when the note authors no value at `<system>.system.<to>`. Dotted for
+ *   a path into a shared container (`data.portrait`), which is now the ordinary
+ *   case: `data:` (#128) puts every type-specific fact under one.
+ *
+ *   It used to mean "frontmatter key under `sohl:`", and that reading is the
+ *   degenerate case where the shared source and the system destination happen
+ *   to share a name. They constantly do not — one shared `data.portrait` feeds
+ *   `sohl.system.portrait` *and* `hm3.system.bioImage` — so the source is
+ *   declared rather than matched by spelling (#58). The in-block position is
+ *   still read, second, until #126 moves the corpus off it.
+ *
+ *   Absent means the value is not authored at all — see `value`.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
  * @property {(raw: any, ctx: {fm: object, field: FieldSpec}) => any} [read] -
@@ -51,6 +70,15 @@ export function authoredFields(fields: readonly FieldSpec[]): FieldSpec[];
  * @property {any} [default] - Emitted when the note does not carry the field.
  * @property {boolean} [required] - Whether a note must carry it. A required
  *   field's `read` is expected to throw when it is missing.
+ * @property {boolean} [shared] - Whether the field is authored at the note's
+ *   **top level** rather than inside a system block, because what it states is
+ *   not system-specific — a map's background art is the same art whichever
+ *   system reads the note. It changes no reader: the top level is already the
+ *   third step of {@link module:engine/system-block.resolveFieldValue}'s order,
+ *   so the value resolves whichever region carries it. What it tells the
+ *   author-facing surfaces is which of the two is the field's *home*, so a
+ *   message about it names `img` rather than sending an author to `sohl.img`
+ *   (#142).
  * @property {"string"|"number"|"boolean"|"list"|"map"} [kind] - The value's
  *   shape, for the frontmatter linter (#19). Distinct from `shape`, which is
  *   prose for a reader, and from `read`, which is what the compiler does: a
@@ -121,13 +149,25 @@ export const BLANK_IS_DEFAULT: Readonly<{
 }>;
 export type FieldSpec = {
     /**
-     * - Dotted path in the emitted `system` block.
+     * - Dotted path in the emitted `system` block — and,
+     * since #58, the path a note authors the field at directly:
+     * `<system>.system.<to>`.
      */
     to: string;
     /**
-     * - Frontmatter key under `sohl:`, dotted for a
-     * nested one (`impact.die`). Absent means the value is not authored — see
-     * `value`.
+     * - The **shared, top-level property this field draws
+     * from** when the note authors no value at `<system>.system.<to>`. Dotted for
+     * a path into a shared container (`data.portrait`), which is now the ordinary
+     * case: `data:` (#128) puts every type-specific fact under one.
+     *
+     * It used to mean "frontmatter key under `sohl:`", and that reading is the
+     * degenerate case where the shared source and the system destination happen
+     * to share a name. They constantly do not — one shared `data.portrait` feeds
+     * `sohl.system.portrait` *and* `hm3.system.bioImage` — so the source is
+     * declared rather than matched by spelling (#58). The in-block position is
+     * still read, second, until #126 moves the corpus off it.
+     *
+     * Absent means the value is not authored at all — see `value`.
      */
     name?: string | undefined;
     /**
@@ -152,6 +192,18 @@ export type FieldSpec = {
      * field's `read` is expected to throw when it is missing.
      */
     required?: boolean | undefined;
+    /**
+     * - Whether the field is authored at the note's
+     * **top level** rather than inside a system block, because what it states is
+     * not system-specific — a map's background art is the same art whichever
+     * system reads the note. It changes no reader: the top level is already the
+     * third step of {@link module :engine/system-block.resolveFieldValue}'s order,
+     * so the value resolves whichever region carries it. What it tells the
+     * author-facing surfaces is which of the two is the field's *home*, so a
+     * message about it names `img` rather than sending an author to `sohl.img`
+     * (#142).
+     */
+    shared?: boolean | undefined;
     /**
      * - The value's
      * shape, for the frontmatter linter (#19). Distinct from `shape`, which is
@@ -179,3 +231,4 @@ export type FieldSpec = {
      */
     describe: string;
 };
+import { setPath } from "./system-block.mjs";

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

@@ -20,11 +20,25 @@ export function matchesKind(value: unknown, kind: string): boolean;
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
  * @param {object} [opts.index] - The link index, for the reference check. Its
  *   absence skips that check rather than reporting every reference as dead.
+ * @param {Record<string, object>} [opts.vocabulary] - Type → the closed regions
+ *   it declares, as `engine/note-vocabulary.mjs` states them (#128). Supplied
+ *   by the caller for the same reason `schemas` is: this module validates a
+ *   note against whatever its type declares and knows no type names of its
+ *   own. Its absence skips the `data:` and `subType` checks rather than
+ *   reporting every key as unknown.
+ * @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}.
  * @returns {object[]} Findings, each with a locator where one is obtainable.
  */
-export function lintNote(note: object, { schemas, index }: {
+export function lintNote(note: object, { schemas, index, vocabulary, systems }: {
     schemas: Record<string, readonly object[]>;
     index?: object | undefined;
+    vocabulary?: Record<string, object> | undefined;
+    systems?: Readonly<Record<string, {
+        known?: readonly string[];
+        fieldVocabulary?: boolean;
+    }>> | undefined;
 }): object[];
 /**
  * Check every note in a built index against its type's schema.
@@ -32,13 +46,22 @@ export function lintNote(note: object, { schemas, index }: {
  * @param {object} index - From `buildLinkIndex`.
  * @param {object} opts
  * @param {Record<string, readonly object[]>} opts.schemas - Type → declaration.
+ * @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}.
  * @returns {{findings: object[], notes: number}} The findings, and how many
  *   notes were inspected.
  */
-export function lintFrontmatter(index: object, { schemas, references }: {
+export function lintFrontmatter(index: object, { schemas, vocabulary, references, systems }: {
     schemas: Record<string, readonly object[]>;
+    vocabulary?: Record<string, object> | undefined;
     references?: boolean | undefined;
+    systems?: Readonly<Record<string, {
+        known?: readonly string[];
+        fieldVocabulary?: boolean;
+    }>> | undefined;
 }): {
     findings: object[];
     notes: number;
@@ -72,3 +95,25 @@ export function lintFrontmatter(index: object, { schemas, references }: {
  * @type {ReadonlySet<string>}
  */
 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.
+ *
+ * `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.
+ *
+ * @type {Readonly<Record<string, {known?: readonly string[], fieldVocabulary?: boolean}>>}
+ */
+export const DEFAULT_SYSTEM_BLOCKS: Readonly<Record<string, {
+    known?: readonly string[];
+    fieldVocabulary?: boolean;
+}>>;

package/types/engine/generate.d.mts

@@ -10,14 +10,27 @@
  * order among packs of one type — and every one of them is written before the
  * actors pass that reads them.
  *
+ * **Scoped to one system when the caller has one (#58).** A being addresses an
+ * item by `(type, shortcode)`, and that address is unique within one system and
+ * not across two: `skill:sword` is an HM3 skill *and* a SoHL skill, with
+ * different data models behind them. The reference itself is unambiguous — it
+ * sits inside a system block, so position says which it means — but the
+ * resolver has to know which catalogue it is searching, or it resolves the pair
+ * by whichever pack was read first. So an Actor pass reads the Item packs of
+ * **its own** system plus the system-neutral ones, which belong to every
+ * system. Asking for no system reads them all, which is every single-system
+ * build and the behaviour this always had.
+ *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
+ * @param {string|null} [system] - The system whose catalogue is wanted. Omitted
+ *   or `null`, every Item pack is read.
  * @returns {string[]} Each Item pack's JSON directory. Empty when the
  *   repository ships no items at all, which is a legitimate package: the actors
  *   pass accepts an empty list and reports an item it cannot resolve per
  *   `(type, shortcode)` instead, naming the being (#49).
  */
-export function itemPackJsonDirs(config?: object): string[];
+export function itemPackJsonDirs(config?: object, system?: string | null): string[];
 /**
  * The passes to run, ordered so that each one follows the output it reads.
  *

package/types/engine/helpers.d.mts

@@ -62,8 +62,8 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
 }, 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:
+ * (the archetype contract, #604). 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
@@ -79,19 +79,27 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories }?: {
  */
 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.
+ * The value a document's `system.archetype` carries, from the required
+ * `sohl.archetype` frontmatter (#126, sohl#1780).
+ *
+ * A **schema field**, so the tri-state is written out in full rather than
+ * expressed by a key's presence: a number is an archetype at that priority,
+ * and `null` is not an archetype. This is where {@link resolveArchetype}'s
+ * `undefined` becomes the field's `null` — an emitted `undefined` would be
+ * dropped by `JSON.stringify`, leaving the compiled document with no
+ * `archetype` at all and the tri-state readable as two.
+ *
+ * **`0` is an archetype.** It is the priority SoHL's own archetypes ship at,
+ * and it is falsy, so this returns it unchanged and every caller must ask
+ * `typeof v === "number"` rather than testing truthiness.
+ *
+ * @param {object} fm      Parsed frontmatter.
+ * @param {string} label   Human-readable context for error messages.
+ * @returns {number|null}  The archetype priority, or `null` for a document
+ *   that is not an archetype.
  * @throws {Error} When `sohl.archetype` is absent or invalid.
  */
-export function withArchetypeFlag(fm: object, flags?: object, label: string): object;
+export function systemArchetype(fm: object, label: string): number | null;
 /**
  * Generates a compendium-source filename: `Name_id.json` with non-
  * alphanumeric runs replaced by underscores.

package/types/engine/ids.d.mts

@@ -84,6 +84,16 @@ export function pageUuid(entryUuid: string, pageId: string): string;
  * @type {ReadonlySet<string>}
  */
 export const MAP_TYPES: ReadonlySet<string>;
+/**
+ * The map subTypes, which differ only in the canvas defaults derived for them.
+ *
+ * They were three *types* until #174, which cost three entries in the pack
+ * router, three in the claims set and three in every consumer's section config
+ * — for one idea that the specification had always described as one type.
+ *
+ * @type {readonly string[]}
+ */
+export const MAP_SUBTYPES: readonly string[];
 /**
  * Content type → the pack its documents compile into, and the document type
  * that pack holds.

package/types/engine/index.d.mts

@@ -1,14 +1,17 @@
 export * as ids from "./ids.mjs";
+export * as systemBlock from "./system-block.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 noteClaims from "./note-claims.mjs";
 export * as contentPackage from "./content-package.mjs";
 export * as notePackage from "./note-package.mjs";
 export * as retiredFields from "./retired-fields.mjs";
 export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
+export * as noteVocabulary from "./note-vocabulary.mjs";
 export * as contentSlug from "./content-slug.mjs";
 export * as contentAddress from "./content-address.mjs";
 export * as foreignManifests from "./foreign-manifests.mjs";
@@ -21,9 +24,11 @@ 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 documentSubtypes from "./document-subtypes.mjs";
 export * as itemDocs from "./item-docs.mjs";
 export * as wikilinks from "./wikilinks.mjs";
 export * as wikilinkSyntax from "./wikilink-syntax.mjs";
+export * as aliasIndex from "./alias-index.mjs";
 export * as siteIndex from "./site-index.mjs";
 export * as baseCompiler from "./base-compiler.mjs";
 export * as journals from "./journals.mjs";

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

@@ -24,10 +24,27 @@ export function itemTypes(): ReadonlySet<string>;
  * failing as an anonymous `is not a function` (#1504).
  *
  * @param {string} type - The note's `type` frontmatter.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry. Omitted, a type only one registry declares still
+ *   resolves; a contested one throws rather than picking a side.
  * @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;
+export function itemBuilder(type: string, system?: string): (fm: object) => object;
+/**
+ * The frontmatter fields a type's registry entry declares, if any.
+ *
+ * Sparse by design: a type whose entry declares none compiles normally and is
+ * simply undocumented (#22). What reads it is the `system`-block passthrough,
+ * which has to know which paths a declared field already writes before it
+ * writes the rest (#58).
+ *
+ * @param {string} type - The item type.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry.
+ * @returns {readonly object[]|undefined} The declaration, or `undefined`.
+ */
+export function itemFields(type: string, system?: string): readonly object[] | undefined;
 /**
  * The default art for an item type — the image a note of that type is given
  * when it carries no `img:` of its own.
@@ -51,7 +68,9 @@ export function itemBuilder(type: string): (fm: object) => object;
  * One spelling, one meaning, wherever it is written.
  *
  * @param {string} type - the item type.
+ * @param {string} [system] - The system compiling it, where a build declares
+ *   more than one registry.
  * @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;
+export function itemArt(type: string, system?: string): string;

package/types/engine/kb-manifest.d.mts

@@ -24,18 +24,34 @@ export function canonicalKey(pkg: string, type: string, shortcode: string): stri
 /**
  * Reads a canonical key back into its parts.
  *
- * Unambiguous because no package, type or shortcode contains a hyphen — types
- * are bare words and shortcodes are `^[A-Za-z0-9]+$` (#1397).
- *
- * @param {string} key - A canonical key.
- * @returns {{package: string, type: string, shortcode: string}|null} The parts,
- *   or `null` when the key is not in canonical form.
+ * Parsing is plain positional counting: split on the separator, require
+ * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
+ * **The charset rule is what makes that sound** — every segment is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
+ * so the hyphen is purely a separator and the count alone determines every
+ * field. That is enforced at each of the three sources rather than assumed of
+ * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
+ * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * carry a hyphen, no amount of counting would recover the fields and the reader
+ * would need a vocabulary to match against instead.
+ *
+ * **Nothing to read and nothing readable are different answers.** A key that
+ * cannot be canonical — `harn-adventures-skill-melee`, four segments — yields
+ * `null`, while an absent or blank input yields `undefined`. Both are falsy, so
+ * every call site (all of which test the result for truthiness) is unaffected;
+ * the distinction is there so a caller reporting "this key is unreadable" can
+ * tell that it has a key to report about.
+ *
+ * @param {unknown} key - A canonical key, or nothing.
+ * @returns {{package: string, type: string, shortcode: string}|null|undefined}
+ *   The parts; `null` when there is a string that is not in canonical form;
+ *   `undefined` when there is no key at all.
  */
-export function readCanonicalKey(key: string): {
+export function readCanonicalKey(key: unknown): {
     package: string;
     type: string;
     shortcode: string;
-} | null;
+} | null | undefined;
 /**
  * The package-relative address a site-absolute URL records as.
  *
@@ -151,6 +167,17 @@ export function manifestsComplete(localPackages: Iterable<string>, manifestPacka
  * relaxes the build rather than breaking it.
  */
 export const LINK_PACKAGES: readonly string[];
+/**
+ * How many segments a canonical key has, and therefore how many the reader
+ * below counts.
+ *
+ * Named rather than written as a literal because it is the *grammar*, not an
+ * implementation detail of one function: it is the number a change to the
+ * address form would move, and the thing a reader of that change has to find.
+ *
+ * @type {number}
+ */
+export const CANONICAL_KEY_SEGMENTS: number;
 /**
  * Manifest format version.
  *

package/types/engine/map-notes.d.mts

@@ -6,14 +6,19 @@
  */
 export function isMapType(type?: string): boolean;
 /**
- * The canvas profile for a map type.
+ * The canvas profile for a map subType.
  *
- * @param {string} type - The note's `type`.
- * @returns {object} The profile from {@link MAP_TYPE_PROFILES}.
- * @throws {Error} When the type is not a map type — the build's fail-fast
- *   contract, so a typo never ships a scene with Foundry's own defaults.
+ * Keyed on the subType rather than the type since #174: every map note is
+ * `type: map`, and which canvas it derives is the one thing the three
+ * spellings ever decided.
+ *
+ * @param {string} subType - The note's `subType`.
+ * @returns {object} The profile from {@link MAP_SUBTYPE_PROFILES}.
+ * @throws {Error} When the subType is not a map subType — the build's
+ *   fail-fast contract, so a typo never ships a scene with Foundry's own
+ *   defaults.
  */
-export function mapProfile(type: string): object;
+export function mapProfile(subType: string): object;
 /**
  * The id of one region within its scene.
  *
@@ -141,7 +146,7 @@ export function buildShape(spec: object, geom: MapGeometry): object;
  */
 export function buildScene(fm: object, ctx: object): object;
 /**
- * Synthesise the scene's single embedded Level from `image:` / `overlay:`.
+ * Synthesise the scene's single embedded Level from `img:` / `overlay:`.
  *
  * Authors never write `levels:`. A scene must ship at least one Level — the
  * client-side `_preCreate` net that would create one does not run for offline
@@ -151,9 +156,13 @@ export function buildScene(fm: object, ctx: object): object;
  *
  * @param {object} sohl - The note's `sohl:` block.
  * @param {string} sceneId - The owning scene's `_id`.
+ * @param {string} [img] - The background art, already resolved from the note.
+ *   Passed by {@link buildScene}, which reads it from the note rather than from
+ *   the block; defaults to whichever spelling the block itself carries, so a
+ *   direct two-argument call still works (#142).
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl: object, sceneId: string): object;
+export function buildLevel(sohl: object, sceneId: string, img?: string): object;
 /**
  * Compile the `walls:` and `doors:` blocks into Wall documents.
  *
@@ -225,9 +234,8 @@ export function buildLocations(sohl: object, geom: MapGeometry, ctx: object): ob
  * @returns {object[]} The Region documents.
  */
 export function buildRegions(sohl: object, geom: MapGeometry, ctx: object): object[];
-export { MAP_TYPES };
 /**
- * Per-type canvas defaults, emitted **explicitly** on every scene.
+ * Per-subtype canvas defaults, emitted **explicitly** on every scene.
  *
  * This is not a convenience. `grid.type`, `grid.distance` and `grid.units` all
  * declare `initial: () => game.system.grid.*`, and there is no `game` at build
@@ -237,7 +245,7 @@ export { MAP_TYPES };
  *
  * @type {Readonly<Record<string, object>>}
  */
-export const MAP_TYPE_PROFILES: Readonly<Record<string, object>>;
+export const MAP_SUBTYPE_PROFILES: Readonly<Record<string, object>>;
 /**
  * Foundry's own id for the level a scene is created with
  * (`Scene.metadata.defaultLevelId`). Adopting it makes every reference to the
@@ -280,4 +288,6 @@ export type MapGeometry = {
      */
     dimensions: number[];
 };
+import { MAP_SUBTYPES } from "./ids.mjs";
 import { MAP_TYPES } from "./ids.mjs";
+export { MAP_SUBTYPES, MAP_TYPES };

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

@@ -0,0 +1,113 @@
+/**
+ * The note types a pass of one document type claims — the claim table.
+ *
+ * Each row restates one pass's `selects`, in the only form that can be asked of
+ * a pack the configuration does not declare. A document type no compiler is
+ * registered for claims nothing, which is what keeps a prebuilt `Adventure`
+ * pack from appearing to answer for any note.
+ *
+ * @param {string} docType - The Foundry document type a pack holds.
+ * @param {ClaimSources} [sources] - What to answer from. Defaults to the
+ *   configured registries and the systems this toolchain ships.
+ * @returns {ReadonlySet<string>} The note types such a pass would claim.
+ */
+export function noteTypesClaimedBy(docType: string, sources?: ClaimSources): ReadonlySet<string>;
+/**
+ * Every note type some pack in a configuration would compile.
+ *
+ * The union across the configured pack list, so a type claimed by any one pack
+ * is claimed — which is what keeps a type deliberately unmapped for one system,
+ * and claimed for another, silent (#79).
+ *
+ * @param {object} [config] - The resolved build configuration. Defaults to this
+ *   repository's.
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @returns {ReadonlySet<string>} The claimed note types.
+ */
+export function claimedNoteTypes(config?: object, sources?: ClaimSources): ReadonlySet<string>;
+/**
+ * Every note type this build knows, whatever any one repository configures.
+ *
+ * Wider than {@link claimedNoteTypes} on purpose: it is what distinguishes a
+ * repository that has not configured a pack for a real content type from an
+ * author who wrote a word nothing anywhere compiles. The engine's own types,
+ * the types every shipped system maps, and whatever the configured registries
+ * declare on top.
+ *
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @returns {ReadonlySet<string>} The vocabulary.
+ */
+export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
+/**
+ * Every note in the content tree that no configured pack would compile.
+ *
+ * Read-only: it walks the tree and reports, and writes nothing. Three kinds of
+ * note are passed over, each for a stated reason rather than by omission — a
+ * file with no frontmatter is not a note; a note with no `type:` is the
+ * frontmatter linter's finding, which can say what a type is *for*; and a
+ * retired type is answered by `assertTypeNotRetired` in `ids.mjs`, which names the
+ * replacement.
+ *
+ * @param {object} [config] - The resolved build configuration. Defaults to this
+ *   repository's.
+ * @param {ClaimSources} [sources] - What to answer from.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string, type: string}>} One finding per note.
+ */
+export function unclaimedNoteFindings(config?: object, sources?: ClaimSources): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "error";
+    message: string;
+    type: string;
+}>;
+/**
+ * Note types that compile into **no compendium document, by design**.
+ *
+ * A homepage compiles into a *page*: it carries no compendium UUID, appears in
+ * no pack and in no link-manifest entry, and every package that publishes one
+ * would otherwise be told its front page is unclaimed. It is the one type whose
+ * absence from every pack is the intended state rather than a gap.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const NEVER_PACKED_TYPES: ReadonlySet<string>;
+/**
+ * The note-type → document-subtype maps this toolchain ships.
+ *
+ * One today. `hm3/` is #139, and when it lands its map joins this list rather
+ * than the claim table below growing a second copy of the same fact.
+ *
+ * `engine/` importing from `sohl/` is the arrangement `generate.mjs` already
+ * has — its `COMPILERS` table names the SoHL compilers by class — and for the
+ * same reason: the engine owns the *mechanism* that asks each system what it
+ * compiles, and the systems own the answers.
+ *
+ * @type {readonly import("./document-subtypes.mjs").DocumentSubtypeMap[]}
+ */
+export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[];
+/**
+ * What a claim question is asked against.
+ *
+ * Each field defaults to what the compilers themselves read, so the answer here
+ * and the answer a pass gives are drawn from one source. They are parameters so
+ * that a test can pose a configuration this toolchain does not ship — two
+ * systems cutting the vocabulary differently, a registry declaring nothing —
+ * without a content tree or a config file on disk.
+ */
+export type ClaimSources = {
+    /**
+     * -
+     * The systems' note-type → document-subtype maps.
+     */
+    maps?: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[] | undefined;
+    /**
+     * - The declared item vocabulary.
+     */
+    itemTypes?: ReadonlySet<string> | undefined;
+    /**
+     * - The doc-carrying types.
+     */
+    docEntryTypes?: ReadonlySet<string> | undefined;
+};