@heroiclands/package-build 22.5.1 → 22.7.0

package/types/engine/actor-compiler.d.mts

@@ -199,6 +199,17 @@ export function loadItemsMap(itemsSourceDirs: readonly string[], foreignSourceDi
  * becomes embedded items. Nothing above that line is a system's business.
  */
 export class SystemActorCompiler extends BasePackCompiler {
+    /**
+     * The Foundry document class this pass writes.
+     *
+     * Declared by the class that does the writing, so the table pairing a
+     * system with its passes is derived from the passes themselves rather than
+     * written out a second time — see
+     * {@link module:engine/generate.systemCompilers}.
+     *
+     * @type {string}
+     */
+    static documentClass: string;
     /**
      * The note-type → document-subtype map this pass compiles against.
      *

package/types/engine/base-compiler.d.mts

@@ -82,13 +82,16 @@ export class BasePackCompiler {
     static readsPackOutputOf: readonly string[];
     /**
      * Whether this pass's document **is** a system's data, and therefore takes
-     * only notes that carry that system's block.
+     * only notes that carry the block this pass reads.
      *
-     * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
-     * and an `actors-sohl` from one tree — and the note-side half of that is
-     * the block named after the system. A note carrying no such block has
-     * nothing to say about it, so compiling it there would emit a **hollow
-     * document**: a subtype, and none of the fields the subtype exists for.
+     * The question is asked of {@link BasePackCompiler#system} — the pass's own
+     * system, which an Actor or Item pass always has — rather than of the
+     * pack's `system:`, which a pack need not declare. A note carrying no such
+     * block has nothing to say about that system, so compiling it would emit a
+     * **hollow document**: a subtype, and none of the fields the subtype exists
+     * for. `harn-ensemble` ships an `actors-hm3` and an `actors-sohl` from one
+     * tree, and `sohl-thalorna` ships one `actors` declaring nothing; the rule
+     * is the same in both, because it is the pass that reads a block.
      *
      * False by default, because most passes write documents that are not
      * system data at all. A JournalEntry of prose is the same document under
@@ -265,22 +268,49 @@ export class BasePackCompiler {
      *   routes to no pack at all — a build failure, never a silent drop.
      */
     routesHere(fm: object): boolean;
+    /**
+     * The system block this pass reads, where it reads one.
+     *
+     * `undefined` on the base class, because most passes read none: a
+     * JournalEntry, a Macro, a Scene and an Adventure are Foundry's documents
+     * rather than any system's. The Actor and Item passes answer with the
+     * block their {@link SystemActorCompiler.documentSubtypes} names, which is
+     * the same declaration that says which notes they claim and what each
+     * becomes.
+     *
+     * Stated here so {@link BasePackCompiler#eligibleFor} is total: a pass
+     * declaring `requiresSystemBlock` without a system reads no block, and a
+     * note can carry nothing for it.
+     *
+     * @returns {string|undefined} The block key, or `undefined`.
+     */
+    get system(): string | undefined;
     /**
      * Whether a claimed, routed note may become this pack's document at all.
      *
-     * The pack-eligibility gate, and it fails rather than skipping: a note that
-     * routed *here* and carries nothing for this pack's system is an authoring
-     * mistake with a hollow document at the end of it, not a note that belongs
-     * to another pass. Skipping it quietly is how a whole tree compiles to
-     * documents nobody can use.
+     * **A system block is what makes a game document.** A pass whose document
+     * *is* a system's data compiles a note only where the note carries the
+     * block that pass reads, so a note saying nothing about any system becomes
+     * no Actor and no Item anywhere — its prose still compiles into a page, a
+     * PDF leaf and a JournalEntry, which are documents no system defines.
+     *
+     * Asked of this pass's own {@link BasePackCompiler#system}, never of the
+     * pack's `system:`. A pack declaring none is a single-system convenience
+     * compiled by the fallback pass for its document type, and that pass still
+     * reads exactly one block — so the note-side question is the same one
+     * whether or not the pack answered it.
+     *
+     * A note this pass has nothing to compile is **skipped**, counted like any
+     * other note the pack does not own. A deliberately unstatted person is the
+     * ordinary case, and a block deleted by accident shows in the diff that
+     * deleted it; what would otherwise be discarded in silence is the block
+     * written for a system no pack of the class serves, and that is reported by
+     * {@link module:engine/note-claims.unclaimedNoteFindings} rather than here,
+     * where a pass can see only its own half of the configuration.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True when the note may be compiled here; `false` when
-     *   it belongs to another system's pass of the same document type, which is
-     *   skipped as quietly as any other note this pack does not own.
-     * @throws {Error} When this pack's system is absent from the note and no
-     *   other configured system claims it. The error carries a `position` where
-     *   the note's own file can be read.
+     *   it carries nothing for this pass's system.
      */
     eligibleFor(fm: object): boolean;
     /**

package/types/engine/draft-notice.d.mts

@@ -0,0 +1,77 @@
+/**
+ * The notice as HTML, for a JournalEntry page and for an Actor's prose field.
+ *
+ * A `blockquote` because that is the element Foundry already sets apart —
+ * `body.game .app blockquote` carries a left rule and an indent — so the
+ * treatment survives with no stylesheet of this package's own. The mark is a
+ * Font Awesome element, which Foundry bundles; `aria-hidden` keeps it out of a
+ * screen reader, where the label reads it.
+ *
+ * @returns {string} The notice's HTML.
+ */
+export function draftNoticeHtml(): string;
+/**
+ * The notice a note has earned, or nothing.
+ *
+ * The one place the tag is asked about on a compiled document, so the packs and
+ * the book cannot answer it differently. It reads {@link
+ * module:engine/note-vocabulary.isDraftNote}, which is the single reader of the
+ * tag itself.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {string} The notice's HTML, or `""` for a note that is settled.
+ */
+export function draftNoticeFor(fm: object | null | undefined): string;
+/**
+ * Prose led by the notice, where the note is a draft.
+ *
+ * **Which field a system leads is the system's decision, and it makes it
+ * once.** A referee at the table opens an actor sheet rather than the
+ * documentation beside it, so the prose a sheet draws says it too — on one
+ * field, since a document showing the same statement twice teaches a reader to
+ * skip it. Both systems put it on the dossier: SoHL's `dossier` and HM3's
+ * `biography` read the same authored section, so the notice lands on the same
+ * prose whichever system compiles it.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} html - The rendered prose.
+ * @returns {string} The prose, led by the notice where one is due.
+ */
+export function withDraftNotice(fm: object | null | undefined, html: string): string;
+/**
+ * The `#let` the book's notice is drawn by.
+ *
+ * Emitted with the rest of the book's preamble. The mark is a circle with an
+ * exclamation set inside it: two primitives and the face already setting the
+ * page, so there is no font to resolve and nothing that can come out as a box.
+ *
+ * @returns {string} The Typst definition.
+ */
+export function bookDraftNoticePreamble(): string;
+/**
+ * The notice as Typst, for a leaf of the book.
+ *
+ * @returns {string} The call, ready to sit between the entry's plate and its
+ *   infobox panel.
+ */
+export function draftNoticeTypst(): string;
+/** The word that opens the notice, and the only part a reader reads as a label. */
+export const DRAFT_NOTICE_LABEL: "Draft.";
+/**
+ * The sentence, which states the fact and stops.
+ *
+ * It says the content may change rather than that the writing is rough,
+ * because that is the difference between a reader who treats the entry as
+ * provisional and one who builds on it. It gives no instruction: a notice that
+ * reaches one page in seven wears better as a statement than as a direction,
+ * and the fact carries the consequence for anyone who can act on it.
+ *
+ * @type {string}
+ */
+export const DRAFT_NOTICE: string;
+/** The Font Awesome mark: a notice, not a hazard. */
+export const DRAFT_NOTICE_ICON: "fa-circle-exclamation";
+/** The class a package may style the HTML notice against. */
+export const DRAFT_NOTICE_CLASS: "sohl-draft-notice";
+/** The Typst function the book's notice calls. */
+export const BOOK_DRAFT_NOTICE: "book-draft-notice";

package/types/engine/generate.d.mts

@@ -1,11 +1,40 @@
+/**
+ * The system-specific compilers, derived from the passes themselves.
+ *
+ * A repository feeding two systems declares one Item pack and one Actor pack
+ * per system — `harn-ensemble` has `actors-hm3` and `actors-sohl` — and each
+ * pack's `system:` is what says whose data model its documents are shaped for.
+ * That is the same field the `_stats` stamp, the item-catalogue scope and the
+ * `itemBuilders` lookup already read, so nothing new is declared to make the
+ * compiler follow it.
+ *
+ * @param {readonly Function[]} passes - The system passes to table.
+ * @returns {Readonly<Record<string, Readonly<Record<string, Function>>>>}
+ *   System id → document class → pass.
+ * @throws {Error} When a pass declares no system or no document class, which is
+ *   a pass that cannot be addressed by either question this table answers.
+ */
+export function systemCompilers(passes: readonly Function[]): Readonly<Record<string, Readonly<Record<string, Function>>>>;
 /**
  * The compiler class a pack of one document type and one system gets.
  *
+ * A pack declaring **no** system takes the fallback pass for its document
+ * class, which reads
+ * {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} — the
+ * single-system convenience every tree shipping for one system is built on.
+ *
+ * A pack declaring a system this toolchain has no pass for is **refused by
+ * name**. Falling through to the fallback would compile that pack out of
+ * another system's blocks and ship it stamped with the system it asked for,
+ * which is the quiet failure the refusal exists to replace.
+ *
  * @param {string} docType - The Foundry document type the pack holds.
  * @param {string|null} [system] - The system the pack declares, if any.
  * @returns {Function|undefined} The compiler class, or `undefined` for a
  *   document type nothing here compiles — which {@link generatePack} reports
  *   rather than defaulting past.
+ * @throws {Error} When a system-bearing document class is asked for a system
+ *   this toolchain ships no pass for.
  */
 export function compilerFor(docType: string, system?: string | null): Function | undefined;
 /**

package/types/engine/index.d.mts

@@ -16,6 +16,7 @@ export * as homepage from "./homepage.mjs";
 export * as noteSchemas from "./note-schemas.mjs";
 export * as noteVocabulary from "./note-vocabulary.mjs";
 export * as noteState from "./note-state.mjs";
+export * as draftNotice from "./draft-notice.mjs";
 export * as stubLint from "./stub-lint.mjs";
 export * as placeRelations from "./place-relations.mjs";
 export * as holdings from "./holdings.mjs";

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

@@ -10,24 +10,23 @@ export function infoboxFor(system: string | undefined): object | undefined;
  * Whether one system compiles a document for one note.
  *
  * This is what a system box's _available_ asserts, and it is the compile's own
- * question rather than a reading of the frontmatter. A note carrying no block
- * is not a note a system has nothing for: where the pack compiling its document
- * declares no `system:`, the document is built from `data:` and the field
- * defaults and ships exactly like any other.
+ * question rather than a reading of the frontmatter.
  *
  * Three statements answer it, and they are the three the compile itself
  * follows:
  *
- * 1. **The map** says which document class this system makes of the note's
+ * 1. **The note's block.** A system block is what makes a game document, so a
+ *    note carrying nothing for this system compiles into no document of it
+ *    anywhere — the rule
+ *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
+ *    asked here from outside.
+ * 2. **The map** says which document class this system makes of the note's
  *    type. No row, no document — and no box either, which is why a caller
  *    reaching here already has one.
- * 2. **The router** says which pack that document goes to, read from the pack
- *    list this build is driven by.
- * 3. **That pack's `system:`** decides the rest. Declaring one, it writes that
- *    system's data and takes only notes that say something about it — the rule
- *    {@link module:engine/base-compiler.BasePackCompiler#eligibleFor} applies,
- *    asked here from outside. Declaring none, it is compiled by the fallback
- *    pass, which needs no block and answers for
+ * 3. **The router** says which pack that document goes to, read from the pack
+ *    list this build is driven by, and **that pack's `system:`** decides whose
+ *    it is. Declaring one, it writes that system's data. Declaring none, it is
+ *    compiled by the fallback pass, which reads
  *    {@link module:engine/subtype-registry.DEFAULT_DOCUMENT_SUBTYPES} alone —
  *    so a tree with no HM3 pack ships no HM3 document however a note is
  *    written.

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

@@ -29,6 +29,17 @@ export function itemDescription(markdown: string, fm: object, name: string): str
  * a configuration one.
  */
 export class SystemItemCompiler extends BasePackCompiler {
+    /**
+     * The Foundry document class this pass writes.
+     *
+     * Declared by the class that does the writing, so the table pairing a
+     * system with its passes is derived from the passes themselves rather than
+     * written out a second time — see
+     * {@link module:engine/generate.systemCompilers}.
+     *
+     * @type {string}
+     */
+    static documentClass: string;
     /**
      * The note-type → document-subtype map this pass compiles against.
      *

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

@@ -2,10 +2,10 @@
  * Every content type whose **prose compiles into a JournalEntry of its own**,
  * addressed by the virtual `doc<type>` qualifier.
  *
- * Every item type, plus `macro` — a macro note's body documents the script the
- * note also compiles into a Macro, which is the same shape as an item
- * and its description: one note, two documents, the prose living in the
- * journals pack.
+ * Every item type, every actor type, every map type, plus `macro` — a macro
+ * note's body documents the script the note also compiles into a Macro, which
+ * is the same shape as an item and its description: one note, two documents,
+ * the prose living in the journals pack.
  *
  * **One set, read by the compiler and the emitter alike.** The journals pass
  * decides what to compile from it, and the link manifest decides what to
@@ -14,8 +14,9 @@
  * consumer can address. It is composed exactly once, in `defineConfig`, and
  * read from there — never recomposed at a call site.
  *
- * `doc` notes and actors are absent: each is a single document, so it has no
- * separate documentation to address.
+ * `doc` notes are absent, for the reason that applies to them alone: a `doc`
+ * note's single document *is* its prose, so there is no second document for a
+ * `doc<type>` address to name.
  *
  * An accessor rather than a hoisted constant, so that importing this module
  * needs no configuration (#2).
@@ -28,8 +29,8 @@ export function docEntryTypes(): ReadonlySet<string>;
  * its own.
  *
  * @param {string} type - The note's `type` frontmatter.
- * @returns {boolean} True for an item type, for `macro` and for a map type;
- *   false for `doc` and for actors.
+ * @returns {boolean} True for an item type, an actor type, a map type and
+ *   `macro`; false for `doc`.
  */
 export function hasDocEntry(type: string): boolean;
 /**

package/types/engine/journals.d.mts

@@ -143,9 +143,14 @@ export function buildPages(rawPages: Array<object>, entryId: string, noteName: s
  *   that reads. It is **not** a page of its own — a page is what a UUID
  *   addresses, and a summary a reader has to navigate to is a summary they do
  *   not see.
+ * @param {string} [params.notice] - A statement about the entry rather than
+ *   about its subject, already rendered to HTML — see {@link
+ *   module:engine/draft-notice}. It leads the first page, ahead of the infobox,
+ *   because a reader deciding whether to rely on the entry has to be told
+ *   before they read it rather than after.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
-export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infobox, }: {
+export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, stats, infobox, notice, }: {
     id: string;
     name: string;
     markdown: string;
@@ -154,6 +159,7 @@ export function buildJournalEntry({ id, name, markdown, leadName, folder, flags,
     flags?: object | undefined;
     stats?: object | undefined;
     infobox?: string | undefined;
+    notice?: string | undefined;
 }): object;
 /**
  * Journals pack compiler.

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

@@ -102,7 +102,12 @@ export function claimedNoteTypes(config?: object, sources?: ClaimSources): Reado
  */
 export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
 /**
- * Every note in the content tree that no configured pack would compile.
+ * Every note in the content tree that no configured pack would compile, and
+ * every system block no configured pack would read.
+ *
+ * Two questions of one walk, because they are the same question asked of a
+ * note's type and of a note's systems, and a note can fail either while passing
+ * the other — see {@link discardedSystemBlockFindings}.
  *
  * 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

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

@@ -50,12 +50,15 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.m
 /**
  * The map a pack declaring no `system:` compiles its documents against.
  *
- * A pack names the system its documents are shaped for, and one declaring none
- * is compiled by the fallback pass for its document type — a single-system
+ * **The single-system fallback, and not a default any system inherits.** A pack
+ * names the system its documents are shaped for, and one declaring none is
+ * compiled by the fallback pass for its document type — a single-system
  * package's ordinary arrangement, and the one `sohl-thalorna` ships. That pass
- * follows one map whatever a note carries, which makes this the answer to "a
- * document compiled here belongs to *which* system?" wherever a pack has not
- * said.
+ * reads this map's block and no other, so a note carrying nothing for this
+ * system compiles into no document there; a note carrying another system's
+ * block reaches that system's pass or nothing at all, never this one. This is
+ * the answer to "a document compiled here belongs to *which* system?" wherever
+ * a pack has not said, and it answers nothing about a system that has said.
  *
  * Stated here rather than read off the compiler classes because those are not
  * reachable from a leaf: `engine/item-compiler.mjs` imports the journals pass,
@@ -67,6 +70,30 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS: readonly import("./document-subtypes.m
  * @type {import("./document-subtypes.mjs").DocumentSubtypeMap}
  */
 export const DEFAULT_DOCUMENT_SUBTYPES: import("./document-subtypes.mjs").DocumentSubtypeMap;
+/**
+ * Every system this toolchain ships a map for, by id.
+ *
+ * Derived from {@link KNOWN_DOCUMENT_SUBTYPE_MAPS}, so registering a map is the
+ * whole of adding a system to every reader that asks "which systems are there?"
+ * — the per-system findings among them.
+ *
+ * @type {readonly string[]}
+ */
+export const SHIPPED_SYSTEMS: readonly string[];
+/**
+ * The Foundry document classes a system compiles its own data into.
+ *
+ * Derived from the shipped maps' rows, so it is the set of classes for which
+ * "which system?" is a question with consequences: a pack of one of these
+ * classes is compiled by one system's pass reading one system's block, and a
+ * note carrying no such block produces nothing there. Every other class — a
+ * JournalEntry, a Macro, a Scene, an Adventure — has one implementation
+ * whatever a pack declares, because it is Foundry's document rather than any
+ * system's.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const SYSTEM_DOCUMENT_CLASSES: ReadonlySet<string>;
 /**
  * Every note type any shipped map compiles into an **Actor**.
  *