@heroiclands/package-build 0.6.1 → 3.0.0

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

@@ -0,0 +1,283 @@
+/**
+ * Whether a content note's type compiles into a Scene.
+ *
+ * @param {string} [type] - The note's `type` frontmatter.
+ * @returns {boolean} True for a map type.
+ */
+export function isMapType(type?: string): boolean;
+/**
+ * The canvas profile for a map type.
+ *
+ * @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.
+ */
+export function mapProfile(type: string): object;
+/**
+ * The id of one region within its scene.
+ *
+ * Derived rather than stored so a cross-reference (`teleportToken`,
+ * `toggleBehavior`) can be resolved to a UUID before the target scene has been
+ * compiled. An authored `_id` always wins — the converter pins ids on
+ * write-back exactly as it does for items and actors.
+ *
+ * @param {string} sceneId - The owning scene's `_id`.
+ * @param {string} key - The region's authored key.
+ * @param {string} [pinned] - An authored `_id`, if any.
+ * @returns {string} A 16-character Foundry id.
+ */
+export function regionDocId(sceneId: string, key: string, pinned?: string): string;
+/**
+ * The id of one behaviour within its region.
+ *
+ * @param {string} regionId - The owning region's `_id`.
+ * @param {string} key - The behaviour's authored key.
+ * @param {string} [pinned] - An authored `_id`, if any.
+ * @returns {string} A 16-character Foundry id.
+ */
+export function behaviorDocId(regionId: string, key: string, pinned?: string): string;
+/**
+ * A region's highlight colour, derived from its key.
+ *
+ * Foundry's default is `Color.fromHSV([Math.random(), 0.8, 0.8])` — a different
+ * value on every create, which would make each build's output differ from the
+ * last for no reason anyone could see. Hashing the key keeps builds
+ * reproducible and diffs quiet, in the same hue/saturation family Foundry
+ * itself would have chosen, and keeps the value out of the note entirely.
+ *
+ * @param {string} key - The region's authored key.
+ * @returns {string} A CSS hex colour.
+ */
+export function regionColor(key: string): string;
+/**
+ * The map's own measurements, from which both unit lints are derived.
+ *
+ * @typedef {object} MapGeometry
+ * @property {string} label - The authored key, for error messages.
+ * @property {number} pxPerGrid - Pixels per grid square.
+ * @property {number[]} dimensions - `[width, height]` in pixels.
+ */
+/**
+ * Reject geometry authored in grid squares where pixels belong.
+ *
+ * A grid-valued wall or region is not rejected by Foundry: it becomes a
+ * 12x11-pixel feature in the top-left corner, invisible on the map and
+ * impossible to notice in a diff. The test is derived from the map itself
+ * rather than a magic number — when every coordinate of one feature is smaller
+ * than a single grid square, on a map several squares across, the author
+ * counted squares.
+ *
+ * @param {number[]} coords - The feature's coordinates, in pixels.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @throws {Error} When the coordinates read as grid units.
+ */
+export function assertPixelGeometry(coords: number[], geom: MapGeometry): void;
+/**
+ * Reject a map pin authored in pixels where grid squares belong.
+ *
+ * @param {number[]} at - The pin's `[x, y]`, in grid squares.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @throws {Error} When the coordinates read as pixels.
+ */
+export function assertGridLocation(at: number[], geom: MapGeometry): void;
+/**
+ * Compile a wall's `blocks:` / `limits:` lists into Foundry's four numeric
+ * restriction fields.
+ *
+ * The authored vocabulary is deliberately not Foundry's.
+ * `WALL_MOVEMENT_TYPES.NONE` means movement does **not** collide — i.e.
+ * passable — so `movement: none` reads as the exact opposite of what it does.
+ * `blocks:` says what the wall stops and `limits:` what it merely attenuates;
+ * anything unnamed is passable.
+ *
+ * @param {{blocks?: string[], limits?: string[]}} spec - The authored lists.
+ * @param {string} label - The authored key, for error messages.
+ * @returns {{move: number, sight: number, light: number, sound: number}} The
+ *   Wall restriction fields.
+ * @throws {Error} On an unknown sense, a sense in both lists, or a *limited*
+ *   movement restriction (movement is binary — it has no LIMITED value).
+ */
+export function wallRestrictions(spec: {
+    blocks?: string[];
+    limits?: string[];
+}, label: string): {
+    move: number;
+    sight: number;
+    light: number;
+    sound: number;
+};
+/**
+ * Compile one authored shape into a Foundry shape record.
+ *
+ * Four forms only — `rectangle` (`rect` is accepted as its short spelling),
+ * `circle`, `ellipse` and `polygon`. The remaining six Foundry shapes are
+ * template and token-attached forms with no place in an authored map, and
+ * `gridBased` is deliberately not exposed: it re-interprets a shape metrically,
+ * and one unit convention per note is the whole point.
+ *
+ * @param {object} spec - The authored shape entry.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @returns {object} The Foundry shape record.
+ * @throws {Error} On an unknown form, a degenerate polygon, or grid-unit
+ *   coordinates.
+ */
+export function buildShape(spec: object, geom: MapGeometry): object;
+/**
+ * Compile a map note into a Scene document, embedded documents and all.
+ *
+ * Every embedded document carries its own `_key`. This is not decoration: the
+ * compendium CLI writes each one straight to its sublevel by that key, and a
+ * missing one fails the compile with `Key cannot be null or undefined`.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} ctx - The compile context:
+ *   `packageId`, `journalEntryId`, `journalPack` (the pack the note's derived
+ *   JournalEntry landed in), `pageIds` (heading key → page id),
+ *   `resolveRegionRef` / `resolveBehaviorRef` / `resolveEffectRef` (address →
+ *   UUID), `knownActions`, `warnings`, and optionally `folder` and `stats`.
+ * @returns {object} The Scene document, keyed for the pack.
+ * @throws {Error} On any authoring mistake Foundry would accept silently.
+ */
+export function buildScene(fm: object, ctx: object): object;
+/**
+ * Synthesise the scene's single embedded Level from `image:` / `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
+ * pack compilation, and the server-side migration shim is version-gated on
+ * `_stats.coreVersion`, so a pack stamped 14.x+ skips it and ships a scene with
+ * no Level and no map.
+ *
+ * @param {object} sohl - The note's `sohl:` block.
+ * @param {string} sceneId - The owning scene's `_id`.
+ * @returns {object} The Level document, keyed for the pack.
+ */
+export function buildLevel(sohl: object, sceneId: string): object;
+/**
+ * Compile the `walls:` and `doors:` blocks into Wall documents.
+ *
+ * Walls are keyed by **feature** rather than by restriction signature, so a
+ * diff reads "the hayloft walls changed" instead of "line 143 changed", and a
+ * human can find the one wall they meant to move.
+ *
+ * @param {object} sohl - The note's `sohl:` block.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @param {object} ctx - The compile context.
+ * @returns {object[]} The Wall documents.
+ */
+export function buildWalls(sohl: object, geom: MapGeometry, ctx: object): object[];
+/**
+ * Compile the `lights:` block into AmbientLight documents.
+ *
+ * `dim` and `bright` are radii in the scene's **distance units** (Foundry's own
+ * meaning), not pixels; only `position:` is pixels.
+ *
+ * @param {object} sohl - The note's `sohl:` block.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @param {object} ctx - The compile context.
+ * @returns {object[]} The AmbientLight documents.
+ */
+export function buildLights(sohl: object, geom: MapGeometry, ctx: object): object[];
+/**
+ * Compile the `tiles:` block into Tile documents.
+ *
+ * @param {object} sohl - The note's `sohl:` block.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @param {object} ctx - The compile context.
+ * @returns {object[]} The Tile documents.
+ */
+export function buildTiles(sohl: object, geom: MapGeometry, ctx: object): object[];
+/**
+ * Compile the `sounds:` block into AmbientSound documents.
+ *
+ * Positional audio is the one audio mechanism that packages cleanly: `path` is
+ * a plain `FilePathField` with no document reference behind it.
+ *
+ * @param {object} sohl - The note's `sohl:` block.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @param {object} ctx - The compile context.
+ * @returns {object[]} The AmbientSound documents.
+ */
+export function buildSounds(sohl: object, geom: MapGeometry, ctx: object): object[];
+/**
+ * Compile the `locations:` block into Note documents — the map pins.
+ *
+ * A location's key names a heading in the note's body, and the pin points at
+ * the journal page that heading compiled into. `Note.entryId` / `pageId` are
+ * `{idOnly: true}` fields, which return before the compendium guard, so pin
+ * targets survive packing intact — but `Note#entry` resolves by bare id against
+ * the **world** collection, which is why a map with pins ships inside an
+ * Adventure (`keepId: true`).
+ *
+ * @param {object} sohl - The note's `sohl:` block.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @param {object} ctx - The compile context.
+ * @returns {object[]} The Note documents.
+ */
+export function buildLocations(sohl: object, geom: MapGeometry, ctx: object): object[];
+/**
+ * Compile the `regions:` block into Region documents with their behaviours.
+ *
+ * @param {object} sohl - The note's `sohl:` block.
+ * @param {MapGeometry} geom - The map's measurements.
+ * @param {object} ctx - The compile context.
+ * @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.
+ *
+ * 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
+ * time — left to their initial they would throw or ship undefined. The numeric
+ * values are `CONST.GRID_TYPES` and `CONST.FOG_EXPLORATION_MODES`, spelled out
+ * here because the constants module is Foundry's, not ours.
+ *
+ * @type {Readonly<Record<string, object>>}
+ */
+export const MAP_TYPE_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
+ * synthesised level derivable, and matches what Foundry would have produced.
+ */
+export const DEFAULT_LEVEL_ID: "defaultLevel0000";
+/**
+ * The behaviour types a map note may carry (issue #1525, v1).
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const REGION_BEHAVIOR_TYPES: ReadonlySet<string>;
+/**
+ * Behaviour types a map note may **never** carry, and why.
+ *
+ * `executeScript` is banned outright: its `source` is a `JavaScriptField`, so a
+ * note carrying one would compile data into code — the system's top security
+ * constraint (non-negotiable rule 10). There is no escape hatch and no
+ * configuration that re-enables it. `executeMacro` is merely deferred: its
+ * target Macro has to ship in the same Adventure to resolve, and
+ * Adventure-bundled macros are not built yet.
+ *
+ * @type {ReadonlyMap<string, string>}
+ */
+export const BANNED_REGION_BEHAVIOR_TYPES: ReadonlyMap<string, string>;
+/**
+ * The map's own measurements, from which both unit lints are derived.
+ */
+export type MapGeometry = {
+    /**
+     * - The authored key, for error messages.
+     */
+    label: string;
+    /**
+     * - Pixels per grid square.
+     */
+    pxPerGrid: number;
+    /**
+     * - `[width, height]` in pixels.
+     */
+    dimensions: number[];
+};
+import { MAP_TYPES } from "./ids.mjs";

package/types/engine/pack-config.d.mts

@@ -0,0 +1,77 @@
+/**
+ * The nearest configuration file at or above a directory.
+ *
+ * **Two of them in one directory is an error.** Picking one by precedence would
+ * mean a repository mid-conversion silently builds from the file its author is
+ * no longer editing, and the build would look entirely healthy while doing it.
+ * The walk continues past a directory holding none, so a repository may still
+ * sit inside one that has its own.
+ *
+ * @param {string} from - The directory to start from.
+ * @returns {string|undefined} Its absolute path, or `undefined` if the walk
+ *   reaches the filesystem root without finding one.
+ * @throws {Error} When one directory holds more than one of
+ *   {@link CONFIG_FILENAMES}.
+ */
+export function findConfigFile(from: string): string | undefined;
+/**
+ * Turn a parsed YAML configuration into the frozen one the engine reads.
+ *
+ * Three fields exist in a code configuration only because a code file has to
+ * *compute* what a data file can simply be told, and each is derived here from
+ * where the file sits:
+ *
+ * - **`rootDir`** is the configuration's own directory, always. A data file
+ *   cannot write `import.meta.dirname`, and any absolute path it wrote instead
+ *   would be one machine's — so authoring it is rejected rather than honoured.
+ * - **`itemBuilders`** is a *name* (`sohl`), resolved against the built-in
+ *   registries. A registry of a consumer's own is code, and code goes in an
+ *   `.mjs` configuration.
+ * - **`stats.systemVersion`** is derived from the adjacent `package.json` when
+ *   the configuration does not state it. Stating it is still allowed: a
+ *   repository shipping content *for* another package (a module declaring
+ *   `systemId: sohl`) may need a version that is not its own.
+ *
+ * Everything else passes through untouched, to be validated by the one
+ * validator both configuration forms end at.
+ *
+ * @param {unknown} data - The parsed configuration document.
+ * @param {string} configPath - Absolute path of the file it was parsed from.
+ * @returns {import("../config.mjs").ContentBuildConfig} The frozen configuration.
+ * @throws {Error} When the document is not a mapping, declares `rootDir`, or
+ *   names an item-builder registry this package does not ship.
+ */
+export function configFromData(data: unknown, configPath: string): import("../config.mjs").ContentBuildConfig;
+/**
+ * The consuming repository's resolved, frozen configuration.
+ *
+ * Every engine module that needs a configured value calls this, rather than
+ * hoisting one at import: that is what keeps the library importable without a
+ * configuration (#2). The result is memoised, so calling it in a default
+ * parameter — the usual spelling here — costs one property read per call.
+ *
+ * @returns {import("../config.mjs").ContentBuildConfig} The frozen configuration.
+ * @throws {Error} When no configuration file can be found, or the one named
+ *   cannot be loaded. Absence is a defect, not a fallback: without it the
+ *   compilers know neither what to compile nor where to put it.
+ */
+export function loadPackConfig(): import("../config.mjs").ContentBuildConfig;
+/** The stem every consuming repository declares its build under. */
+export const CONFIG_BASENAME: "package-build.config";
+/**
+ * The file names a configuration may be written as, in resolution order.
+ *
+ * Order settles nothing in practice — two of these in one directory is an
+ * error, not a precedence question (see {@link findConfigFile}) — but it fixes
+ * the order the names are *reported* in, which is the order a reader should
+ * reach for them: YAML first, `.mjs` last.
+ *
+ * The `content-build.config.*` stem this package read before the two toolchains
+ * merged is **not** resolved. 2.0.0 renames the file rather than accepting both:
+ * a deprecation window here would mean a repository could sit indefinitely on a
+ * name for a package that no longer exists, and the upgrade already requires
+ * touching the consumer's manifest and imports.
+ *
+ * @type {readonly string[]}
+ */
+export const CONFIG_FILENAMES: readonly string[];

package/types/engine/pack-router.d.mts

@@ -0,0 +1,53 @@
+/**
+ * Build the router for one configured pack list.
+ *
+ * Pure — it reads the list and nothing else, so a consumer's routing can be
+ * tested without a content tree or a config file on disk.
+ *
+ * @param {readonly object[]} packs - The resolved `packs` list from
+ *   `defineConfig`.
+ * @returns {{resolve: (fm: object, docType: string) => string,
+ *   resolveOrNull: (fm: object, docType: string) => string|undefined,
+ *   packsOfType: (docType: string) => string[],
+ *   defaultOf: (docType: string) => string|undefined}} The router.
+ */
+export function createPackRouter(packs: readonly object[]): {
+    resolve: (fm: object, docType: string) => string;
+    resolveOrNull: (fm: object, docType: string) => string | undefined;
+    packsOfType: (docType: string) => string[];
+    defaultOf: (docType: string) => string | undefined;
+};
+/**
+ * The router for a resolved configuration, built once per configuration.
+ *
+ * @param {object} config - A configuration from `defineConfig`.
+ * @returns {ReturnType<typeof createPackRouter>} Its router.
+ */
+export function routerFor(config: object): ReturnType<typeof createPackRouter>;
+/**
+ * The consuming repository's own router — what every module that emits a UUID
+ * asks where a note's document lives.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2). {@link routerFor} keeps one router per
+ * configuration object, so repeated calls return the same instance.
+ *
+ * @returns {ReturnType<typeof createPackRouter>} This repository's router.
+ */
+export function packRouter(): ReturnType<typeof createPackRouter>;
+/**
+ * A note that cannot be routed to a pack. Thrown rather than returned so no
+ * caller can carry on with a plausible-looking default.
+ */
+export class PackRoutingError extends Error {
+    /** @param {string} message */
+    constructor(message: string);
+}
+/**
+ * The frontmatter field a note declares its pack in.
+ *
+ * Deliberately close to `package:` and deliberately not the same word: a note's
+ * `package:` says which *distribution* owns it, `pack:` which *compendium*
+ * receives its document.
+ */
+export const PACK_FIELD: "pack";

package/types/engine/prose-config.d.mts

@@ -0,0 +1,121 @@
+/**
+ * The shared options for one file, with the per-language adjustment applied.
+ *
+ * What a consumer's own Prettier config would have produced, for a repository
+ * that declares none.
+ *
+ * @param {string} file - Path of the file about to be formatted.
+ * @returns {object} Options to hand Prettier directly. Never carries
+ *   `overrides`: passing that inline is what silently did nothing (#76).
+ */
+export function sharedPrettierOptionsFor(file: string): object;
+/**
+ * The prose conventions every content repository writes to — one Prettier
+ * configuration and one markdownlint rule set, declared here so a note
+ * formatted in one repository is formatted the same way in the next (#69).
+ *
+ * These used to exist in exactly one consumer. The SoHL repository carried
+ * both; `sohl-thalorna` had Prettier but never ran it from `lint`; and
+ * `sohl-kethira-basic` had neither, so the package least likely to have been
+ * proofread was checked for addresses and nothing else. A rule set copied into
+ * three repositories is one rule with three implementations, which is the drift
+ * #20 exists to remove — so it is declared once, here, and every consumer
+ * invokes it.
+ *
+ * **Neither of these is an override.** A consumer that declares its own
+ * Prettier config or its own `.markdownlint-cli2.jsonc` wins; what ships here
+ * is the default a repository gets for declaring nothing. Repository *layout*
+ * knowledge — which paths to skip — stays with the repository that has the
+ * layout, in its own ignore files.
+ *
+ * @module
+ */
+/**
+ * The Prettier options every content repository shares, before any per-language
+ * adjustment.
+ *
+ * The values are not arbitrary: they are the ones the SoHL repository has
+ * always used, kept identical here so a module or a note moving between
+ * repositories does not reformat on arrival. Changing one of these reformats
+ * every consumer, so treat it as a breaking change to the shared tree rather
+ * than a preference.
+ *
+ * @type {Readonly<object>}
+ */
+export const PRETTIER_BASE: Readonly<object>;
+/**
+ * What markdown gets on top of {@link PRETTIER_BASE}.
+ *
+ * Markdown indents at 2, not the global 4. Notes are the thing several
+ * repositories exchange, so their indentation is the one value that most needs
+ * to be the same everywhere — a note's YAML frontmatter is nested lists, and at
+ * 4 every note reindents away from the form it was written in.
+ *
+ * **Declared apart from the `overrides` block, not derived from it.** Prettier
+ * applies `overrides` only while resolving a config *file*; options handed to
+ * it directly keep the global values, so a consumer with no config of its own
+ * silently got markdown at 4 (#76). The runner needs the adjustment as data it
+ * can apply itself, and {@link PRETTIER_CONFIG} composes the same values into
+ * the shape a config file wants — one source, two presentations.
+ *
+ * @type {Readonly<object>}
+ */
+export const PRETTIER_MARKDOWN: Readonly<object>;
+/**
+ * The shared configuration in the shape a Prettier **config file** takes.
+ *
+ * This is what a consumer's `prettier.config.mjs` re-exports, and it is the
+ * form in which the markdown adjustment works: resolved from the consumer's own
+ * root, `**\/*.md` matches that repository's markdown. Shipped from inside
+ * `node_modules` it would match nothing, because Prettier resolves an
+ * override's glob relative to the config file's own directory — which is why
+ * the runner applies {@link PRETTIER_MARKDOWN} itself rather than pointing
+ * Prettier at this file.
+ *
+ * @type {Readonly<object>}
+ */
+export const PRETTIER_CONFIG: Readonly<object>;
+/**
+ * The markdownlint rules — the structural checks Prettier cannot make.
+ *
+ * Prettier already formats every hand-written `.md` file, and it is indifferent
+ * to structure: it will happily reformat a document whose heading levels skip
+ * from h3 to h5, whose two sibling sections claim the same anchor, or whose
+ * link is `(text)[url]`. Those are the defects this set is for.
+ *
+ * **THE RULE SET IS DELIBERATELY NARROW, and stays that way on purpose.**
+ * Turning on markdownlint's defaults over a content tree produces tens of
+ * thousands of findings, almost all of them line length, list indentation and
+ * blank-line placement — Prettier's territory, or a second formatter's taste
+ * imposed on prose it already owns. So `default` is off and each rule below is
+ * enabled by name, with the reason it earns its place. Add a rule only if it
+ * can report that a page is *wrong*.
+ *
+ * @type {Readonly<object>}
+ */
+export const MARKDOWNLINT_CONFIG: Readonly<object>;
+/**
+ * The globs `content-build markdown` checks when a consumer names no paths.
+ *
+ * Every markdown file the repository tracks, which is what a consumer means by
+ * "lint my markdown". What to *skip* is the repository's own business and comes
+ * from its `.gitignore` (honoured by default) and its own configuration.
+ *
+ * @type {readonly string[]}
+ */
+export const MARKDOWN_GLOBS: readonly string[];
+/**
+ * Markdown every consumer has and nobody hand-writes.
+ *
+ * `CHANGELOG.md` is assembled by `changeset version` from the `.changeset/*.md`
+ * bodies on every release. It is not in anyone's `.gitignore` — it is
+ * committed — so nothing else excludes it, and linting it reports on the
+ * generator: the findings are real (a heading level changesets chose, an
+ * asterisk it emitted) and unfixable, because the next release rewrites the
+ * file. Every repository here releases through changesets, so this is a fact
+ * about the shared toolchain rather than any one repository's layout, and it
+ * belongs in the default instead of being rediscovered three times.
+ *
+ * @type {readonly string[]}
+ */
+export const MARKDOWN_IGNORES: readonly string[];

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

@@ -0,0 +1,59 @@
+/**
+ * Check — or rewrite — every file Prettier claims, under one root.
+ *
+ * The configuration resolution is the part that matters: a consumer's own
+ * Prettier config, found by Prettier walking up from each file, always wins.
+ * {@link sharedPrettierOptionsFor} is what a file gets when that search finds
+ * nothing, which is the case in a repository that has deliberately declared
+ * none.
+ *
+ * @param {string} root - Repository (or subtree) to check.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.paths] - Files or directories to check
+ *   instead of the whole root.
+ * @param {boolean} [opts.write=false] - Rewrite unformatted files in place
+ *   rather than reporting them.
+ * @param {object} [opts.prettier] - The Prettier module, for tests.
+ * @returns {Promise<{findings: Array<{file: string, severity: string,
+ *   message: string}>, checked: number, written: string[]}>} The findings, how
+ *   many files were considered, and what was rewritten.
+ */
+export function checkFormatting(root: string, opts?: {
+    paths?: readonly string[] | undefined;
+    write?: boolean | undefined;
+    prettier?: object | undefined;
+}): Promise<{
+    findings: Array<{
+        file: string;
+        severity: string;
+        message: string;
+    }>;
+    checked: number;
+    written: string[];
+}>;
+/**
+ * Lint a repository's markdown against the shared rule set.
+ *
+ * {@link MARKDOWNLINT_CONFIG} is passed as markdownlint's `optionsDefault`,
+ * which is precisely the "shipped default, consumer overrides" behaviour the
+ * command promises: a `.markdownlint-cli2.jsonc` found in the tree replaces it,
+ * and a repository with none gets these rules.
+ *
+ * @param {string} root - Repository to lint.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.paths] - Globs to lint instead of every
+ *   markdown file.
+ * @param {boolean} [opts.fix=false] - Apply the fixes markdownlint can make.
+ * @param {(params: object) => Promise<number>} [opts.run] - The
+ *   markdownlint-cli2 entry point, for tests.
+ * @returns {Promise<{findings: object[], exitCode: number}>} The findings, and
+ *   markdownlint's own exit code.
+ */
+export function lintMarkdown(root: string, opts?: {
+    paths?: readonly string[] | undefined;
+    fix?: boolean | undefined;
+    run?: ((params: object) => Promise<number>) | undefined;
+}): Promise<{
+    findings: object[];
+    exitCode: number;
+}>;

package/types/engine/region-events.d.mts

@@ -0,0 +1,43 @@
+/**
+ * The curated Foundry region-event vocabulary, as plain data.
+ *
+ * Deliberately **plain ESM** — no TypeScript, no `@src` aliases, no Foundry —
+ * for the same reason `../sohl/default-item-art.mjs` is: the map-note pack
+ * compiler runs under bare `node`, outside the bundler that resolves `@src` and
+ * strips types, and it must reject an authored region event that the runtime
+ * would silently drop. One list here is what keeps the build-time lint and the
+ * runtime bridge from drifting apart.
+ *
+ * It sits in this package rather than in the system's `src/` tree because the
+ * map-note compiler that reads it is installed as a dependency (#1501), and a
+ * relative path out of the package would resolve to garbage from
+ * `node_modules`. The runtime reaches it back through the package's
+ * `./engine/region-events` entry point (#1510). It is engine-side, not
+ * SoHL-side, because any content module that authors a scene region — an
+ * adventure module included — needs this vocabulary.
+ *
+ * The prose explaining *why* each event is curated or excluded lives with the
+ * typed re-exports in `src/entity/event/region-triggers.ts`, which is the
+ * documented surface.
+ */
+/**
+ * The curated Foundry region-event → SoHL trigger-name map. The keys are the
+ * `CONST.REGION_EVENTS` string values SoHL forwards.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const REGION_EVENT_TO_TRIGGER: Readonly<Record<string, string>>;
+/**
+ * The Foundry region-event names SoHL forwards (the keys of the map).
+ *
+ * @type {readonly string[]}
+ */
+export const CURATED_REGION_EVENTS: readonly string[];
+/**
+ * Region events SoHL deliberately does **not** forward: the continuous
+ * (`tokenMove*`), view-dependent (`tokenAnimate*`) and lifecycle
+ * (`behavior*`, `regionBoundary`) streams.
+ *
+ * @type {readonly string[]}
+ */
+export const EXCLUDED_REGION_EVENTS: readonly string[];

package/types/engine/scene-levels.d.mts

@@ -0,0 +1,36 @@
+/**
+ * The version of `@foundryvtt/foundryvtt-cli` this build actually resolves.
+ *
+ * Resolved from *this* module, so it names the copy the pack compile runs on
+ * rather than whatever a shell happens to find. The installed version is the
+ * write path, so it is the fact a report should carry.
+ *
+ * @returns {string | undefined} The resolved version, or `undefined` when the
+ *   package cannot be read (a pruned install, an exports-restricted copy).
+ */
+export function compendiumCliVersion(): string | undefined;
+/**
+ * Every way a compiled pack can ship a Scene that has lost its Level.
+ *
+ * @param {Iterable<[string, object]>} records - `[key, value]` pairs from a
+ *   compiled pack's LevelDB, in any order.
+ * @param {object} [options] - Reporting context.
+ * @param {string} [options.cliVersion] - The resolved compendium CLI version,
+ *   which decides what a wholesale loss is blamed on. Defaults to unknown,
+ *   which leaves the report to say only what it can prove.
+ * @returns {string[]} One human-readable problem per violation, empty when the
+ *   pack is sound.
+ */
+export function checkSceneLevels(records: Iterable<[string, object]>, { cliVersion }?: {
+    cliVersion?: string | undefined;
+}): string[];
+/**
+ * Read a compiled pack back off disk and check it.
+ *
+ * The pack is opened after the compendium CLI has closed it, so this reads the
+ * bytes that will actually ship rather than the JSON they were compiled from.
+ *
+ * @param {string} packDir - Directory of the compiled LevelDB pack.
+ * @returns {Promise<string[]>} The problems found, empty when the pack is sound.
+ */
+export function verifyPackSceneLevels(packDir: string): Promise<string[]>;