@heroiclands/package-build 22.5.1 → 22.7.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @heroiclands/package-build
 
+## 22.7.0
+
+### Minor Changes
+
+**Draft notes say so.** A note tagged `draft` states that it is unfinished and
+that nothing in it is settled, at the head of its compendium entry, on the
+character sheet a referee opens, and on its page in the book. A finished note
+carries nothing.
+
+## 22.6.0
+
+### Minor Changes
+
+**Compendium content**
+
+- A person or thing with no game-system data no longer becomes a blank
+  compendium entry — the note still publishes its page and its journal, so
+  somebody can be written without being statted.
+- A package carrying data for a game system it ships no compendium for is now
+  told so, rather than having it quietly dropped.
+
 ## 22.5.1
 
 ### Patch Changes

package/CONTENT.md

@@ -867,7 +867,12 @@ has no art.
 A note is **system-agnostic**. The only system-specific things it carries are
 the properties named after a system, and one note may carry more than one — a
 `being` in `harn-ensemble` compiles into a SoHL `being` _and_ an HM3
-`character`. Within a system's block:
+`character`.
+
+**The block is what makes a game document.** A note carrying none produces no
+Actor and no Item at all, in any package; its prose still compiles into a page,
+a PDF page and a JournalEntry, so a person can be written without being statted.
+Within a system's block:
 
 | property           | maps to                                                       |
 | ------------------ | ------------------------------------------------------------- |
@@ -1006,12 +1011,19 @@ hold this package at a build that does not write it. A subtree the schema
 declares but describes no further — a discriminated `TypedSchemaField`, stored
 flat — is left alone rather than reported wholesale.
 
-**A pack that declares a `system:` takes only notes carrying that block.** A
-note that says nothing about a system has no system data, and compiling it there
-would emit a hollow document — a subtype, and none of the fields the subtype
-exists for. The build fails naming the note and the pack. A pack declaring no
-system constrains nothing, and a pass whose document is not system data at all —
-journals, macros, scenes — is not subject to the rule.
+**An Actor or Item pass takes only notes carrying the block it reads.** A note
+that says nothing about a system has no system data, and compiling it would emit
+a hollow document — a subtype, and none of the fields the subtype exists for. So
+a note carrying no block for any system produces no Actor and no Item anywhere,
+and is passed over in silence; its prose still compiles into a page, a PDF page
+and a JournalEntry. The question is asked of the pass's own system rather than
+of the pack's `system:`: a pack declaring none is compiled by the fallback pass,
+which reads one block like any other. A pass whose document is not system data
+at all — journals, macros, scenes — is not subject to the rule.
+
+**A block for a system no pack of the class compiles is an error**, reported
+once per note per system with the position of the block key, because the
+authored data is discarded either way.
 
 **`(type, shortcode)` resolves inside one system's catalogue.** A being names its
 embedded items by address and never by pack, so the Item packs are read as one
@@ -1101,6 +1113,11 @@ page, no address and no link target. A note with a body and the `draft` tag is a
 **draft**, and one with a body and no tag is **full**.
 `docs/content-format.md` states the rule; this is what the lint does with it.
 
+A draft says so on every surface it reaches — its journal entry, the Actor a
+being compiles into, its page in the book — in one sentence at the head of the
+entry, above the infobox and the prose. A stub says nothing anywhere, because it
+publishes nothing to say it on.
+
 **A document that would be empty is not created**, and the index then names no
 artefact — `uuid`, `path` and `address` are `null`. An unwritten note still
 compiles every document derived from `data:`, so an arcane talent is still its

package/docs/api.md

@@ -427,6 +427,23 @@ The three states of a note — **stub**, **draft**, **full** — and the one obs
 | `placeholderBody`     | `placeholderBody(body)`                     | `Array<{phrase: string, line: number}>` | finding a body that reduces to nothing but placeholders, which is an abandoned draft rather than a stub                    |
 | `bodyWordCount`       | `bodyWordCount(body)`                       | `number`                                | counting the prose a reader meets, with a wikilink counting as the one word it renders                                     |
 
+### `engine.draftNotice`
+
+What a draft note says about itself, in one sentence, on every surface it reaches. The words are stated once and each renderer composes its own markup around them, so a reader meeting the note on a page, in a compendium and in the book meets one statement. The mark is a notice rather than a hazard, and the book draws it rather than setting a glyph, because a face missing one is silent in Typst.
+
+| Export                    | Signature                            | Returns  | Use it when                                                                        |
+| ------------------------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------- |
+| `DRAFT_NOTICE`            | `const DRAFT_NOTICE`                 | `string` | reading the sentence itself, which is the floor every surface degrades to          |
+| `DRAFT_NOTICE_LABEL`      | `const DRAFT_NOTICE_LABEL`           | `string` | reading the label that opens the notice                                            |
+| `DRAFT_NOTICE_ICON`       | `const DRAFT_NOTICE_ICON`            | `string` | naming the Font Awesome mark the HTML surfaces draw                                |
+| `DRAFT_NOTICE_CLASS`      | `const DRAFT_NOTICE_CLASS`           | `string` | styling the HTML notice from a package that wants to                               |
+| `BOOK_DRAFT_NOTICE`       | `const BOOK_DRAFT_NOTICE`            | `string` | naming the Typst function the book's notice calls                                  |
+| `draftNoticeHtml`         | `draftNoticeHtml()`                  | `string` | drawing the notice for a JournalEntry page or an Actor's prose field               |
+| `draftNoticeFor`          | `draftNoticeFor(frontmatter)`        | `string` | asking whether a note has earned a notice, which is the one place the tag is asked |
+| `withDraftNotice`         | `withDraftNotice(frontmatter, html)` | `string` | leading a system's own prose field with the notice where one is due                |
+| `draftNoticeTypst`        | `draftNoticeTypst()`                 | `string` | drawing the notice for a leaf of the book                                          |
+| `bookDraftNoticePreamble` | `bookDraftNoticePreamble()`          | `string` | emitting the Typst definition the book's notice is drawn by                        |
+
 ### `engine.stubLint`
 
 An empty body must be deliberate. Four rules hold the state honest — a stub states what it is, a stub is not tagged `draft`, a body that renders to nothing is an abandoned draft, and a short unmarked body is asked whether it forgot its marker — and two reports say what the rules cannot decide.
@@ -627,6 +644,8 @@ Which note-type → document-subtype maps this toolchain ships, and the two ques
 | `KNOWN_DOCUMENT_SUBTYPE_MAPS` | `const KNOWN_DOCUMENT_SUBTYPE_MAPS`      | —                                                                                                                                 | The note-type → document-subtype maps this toolchain ships.                                                                            |
 | `ACTOR_TYPES`                 | `const ACTOR_TYPES`                      | —                                                                                                                                 | Every note type any shipped map compiles into an **Actor**.                                                                            |
 | `DEFAULT_DOCUMENT_SUBTYPES`   | `const DEFAULT_DOCUMENT_SUBTYPES`        | —                                                                                                                                 | The map a pack declaring no `system:` compiles its documents against.                                                                  |
+| `SHIPPED_SYSTEMS`             | `const SHIPPED_SYSTEMS`                  | —                                                                                                                                 | Every system this toolchain ships a map for, by id.                                                                                    |
+| `SYSTEM_DOCUMENT_CLASSES`     | `const SYSTEM_DOCUMENT_CLASSES`          | —                                                                                                                                 | The Foundry document classes a system compiles its own data into.                                                                      |
 | `subtypeMapFor`               | `function subtypeMapFor(system)`         | {import("./document-subtypes.mjs").DocumentSubtypeMap\|undefined} Its map, or `undefined` where this toolchain ships none for it. | The map one system ships, by its id.                                                                                                   |
 | `schemaSubtypeOf`             | `function schemaSubtypeOf(system, type)` | {string} The document subtype to look up.                                                                                         | The document subtype a note type compiles into for one system — the translation the _schema_ check needs, and the reason it needs one. |
 
@@ -1197,6 +1216,7 @@ Pack JSON generation — in-repo Markdown → per-entry JSON (build-only). Reads
 
 | Export                        | Signature                                               | Returns                                                                                                                                                                                                         | Use it when                                                                                                         |
 | ----------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `systemCompilers`             | `function systemCompilers(passes)`                      | {Readonly<Record<string, Readonly<Record<string, Function>>>>} System id → document class → pass.                                                                                                               | The system-specific compilers, derived from the passes themselves.                                                  |
 | `compilerFor`                 | `function compilerFor(docType, system`                  | {Function\|undefined} The compiler class, or `undefined` for a document type nothing here compiles — which {@link generatePack} reports rather than defaulting past.                                            | The compiler class a pack of one document type and one system gets.                                                 |
 | `emittedArtFor`               | `function emittedArtFor(type)`                          | {{document: string\|null, art: readonly string[]}\|null} What the type compiles into and the art it carries there, or `null` where no claim can be made — a retired type, which is reported as retired instead. | The art fields a note of one content type reaches its document through, and the document it reaches.                |
 | `packJsonDir`                 | `const packJsonDir`                                     | {string} The pack's JSON directory.                                                                                                                                                                             | Root of the build-only JSON tree for one pack.                                                                      |

package/docs/content-format.md

@@ -197,13 +197,14 @@ _Not available_ on every affiliation page would suggest a gap in the note when
 the truth is about the system's scope.
 
 Whether a document was produced is the compile's own answer rather than a
-reading of the frontmatter. The note's type must map to the system; the note
-must route to a pack of the document class that map names; and where **that
-pack declares a `system:`**, the note must carry that system's block, which is
-the same rule the pack itself compiles under. A pack declaring **no** system
-compiles every note it claims from `data:` and the field defaults, so a note
-with no block still produces a document and its box still carries content —
-which is the ordinary arrangement in a package built for one system.
+reading of the frontmatter. Three things must hold: the note must carry that
+system's block, its type must map to the system, and it must route to a pack of
+the document class that map names. The block is the first of them because a
+system block is what makes a game document — see
+[A system block is what makes a game document](#a-system-block-is-what-makes-a-game-document).
+A pack declaring **no** system is compiled by the fallback pass, which reads one
+system's block and no other, so the question is the same one whether or not the
+pack answered it.
 
 #### Four section layouts
 
@@ -319,16 +320,51 @@ is declared, so a near miss is a finding that names what you probably meant.
 | **being kind**      | `being`                | `character`, `creature`                                                                                                                                                                                                                                                                                              |
 | **state**           | any                    | `draft`                                                                                                                                                                                                                                                                                                              |
 
-**`draft` is the one tag either build reads.** A note tagged `draft` exists so a
-link into it is not dead, and a link into it renders marked — as
+**`draft` is the one tag either build reads.** It does two things and nothing
+else: a link _into_ a draft note renders marked, and the note itself states that
+it is unfinished wherever a reader meets it.
+
+A link into it renders as
 `<span class="sohl-draft-link" title="Draft — not yet written">…</span>` in a
 compiled journal and on the website alike, with the appearance supplied by the
-consuming system's stylesheet or the site theme. **Nothing else changes**: the
-note compiles, validates, publishes and resolves exactly as any other, and it
-stays in the packs, in the link manifest and on the site. That is what separates
-the tag from the retired `draft:` field, whose whole effect was to move a note
-from published to unresolvable without saying so — and which is refused, by name,
-if you write it.
+consuming system's stylesheet or the site theme.
+
+The note's own statement is the **draft notice**, and it reads the same on every
+surface:
+
+> **Draft.** This entry is unfinished. What it states may change, and nothing in
+> it is settled.
+
+It leads the entry — above the infobox and above the prose — because a reader
+deciding whether to rely on an entry has to be told before they read it. Where
+it lands:
+
+| Surface      | What carries it                                                      |
+| ------------ | -------------------------------------------------------------------- |
+| JournalEntry | a `blockquote.sohl-draft-notice` at the head of the first page       |
+| Actor        | the dossier the sheet draws — SoHL's `dossier`, HM3's `biography`    |
+| The book     | a drawn mark and a left rule between the entry's plate and its panel |
+| The website  | the theme's own notice, above the infobox rail and the prose         |
+
+**An Actor carries it once.** A being's prose reaches two fields, and a document
+saying the same thing twice teaches a reader to skip it — a printed sheet draws
+both in turn — so the dossier carries the notice and the appearance is
+untouched. The two systems pair by the authored section each field reads rather
+than by its name, so `dossier` and `biography` carry it while `appearance` and
+`description` do not.
+
+**The mark is a notice, not a hazard** — `fa-circle-exclamation`, which Foundry
+bundles, so a journal page carries it with no module stylesheet loaded. The book
+draws its own, because a consumer declaring no icon family is the ordinary case
+and a glyph a face lacks is silent in Typst. Stripped of mark and rule the
+sentence still states the whole thing, which is the floor every surface is built
+to.
+
+**Nothing else changes**: the note compiles, validates, publishes and resolves
+exactly as any other, and it stays in the packs, in the link manifest and on the
+site. That is what separates the tag from the retired `draft:` field, whose whole
+effect was to move a note from published to unresolvable without saying so — and
+which is refused, by name, if you write it.
 
 **The group's scope is what makes the check work.** A group names the types it
 applies to, and a place's kinds are only ever checked on a place. Without that
@@ -788,8 +824,9 @@ _compendium_ receives its document.
 — an item's prose compiling into a `JournalEntry` of its own — is not what the
 author was addressing, and is routed by the pass that produces it.
 
-**`<system>.pack` overrides it for one system.** A note that compiles into two
-systems can send each document to its own pack:
+**`<system>.pack` names the pack for one system's document.** Routing is per
+system: each block the note carries sends its own document where that block
+says, and a note carrying two blocks may place them in two packs.
 
 ```yaml
 pack: items-sohl
@@ -797,9 +834,22 @@ hm3:
   pack: items-hm3
 ```
 
-**Unstated, the document goes to the pack of its type marked `default: true`.**
-Where no pack of that type is the default, the build refuses rather than
-guessing, and names the candidates.
+**Unstated, a system's document goes to that system's default pack of its
+class** — the pack of the class declaring that `system:`, or, where none does,
+the pack of the class marked `default: true`. Where nothing answers, the build
+refuses rather than guessing, and names the candidates.
+
+**`pack` and `packFolder` are different questions.** `pack` names _which
+compendium_ receives a document; `packFolder` names the folder note whose
+address the document is filed under _within_ whichever compendium that is. They
+compose, and both are read per system, so a note may place its two systems'
+documents in different packs and different folders:
+
+```yaml
+sohl:
+  pack: characteristics
+  packFolder: miscgear
+```
 
 **`pack: none` compiles the note into no document.** The note is walked,
 published as a page, present in the content index with an address and no
@@ -1662,11 +1712,15 @@ convention rather than declared in a field — see
 A note has three states, and two of them are nothing but conventions the format
 already carried.
 
-| State     | Body    | Marker          | Page        | Document                          | Link target |
-| --------- | ------- | --------------- | ----------- | --------------------------------- | ----------- |
-| **stub**  | empty   | none            | no          | yes, where one would not be empty | no          |
-| **draft** | written | `tags: [draft]` | yes, marked | yes                               | yes         |
-| **full**  | written | none            | yes         | yes                               | yes         |
+| State     | Body    | Marker          | Page         | Document                          | Link target |
+| --------- | ------- | --------------- | ------------ | --------------------------------- | ----------- |
+| **stub**  | empty   | none            | no           | yes, where one would not be empty | no          |
+| **draft** | written | `tags: [draft]` | yes, noticed | yes, noticed                      | yes         |
+| **full**  | written | none            | yes          | yes                               | yes         |
+
+"Document" here is the document a note's frontmatter earns. A system's Actor or
+Item is earned by that system's block, in every state —
+[a system block is what makes a game document](#a-system-block-is-what-makes-a-game-document).
 
 **Full is the absence of everything.** It is the default and carries no marker,
 which is right: the overwhelming majority of a finished corpus should say
@@ -1763,8 +1817,8 @@ cannot be is the target of a wikilink, because a wikilink points at a page.
 
 Note types fall into two groups, and only the first has a mapping table.
 
-**Types producing a system document** — a SoHL or HM3 Actor or Item, one per
-system, described by the tables further down.
+**Types that _may_ produce a system document** — a SoHL or HM3 Actor or Item,
+one per system, described by the tables further down.
 
 **Types producing only a core document** — `lore`, `place`, `scenario`, `doc`,
 `map`, `macro` and `homepage`. A core document is one Foundry defines rather than
@@ -1780,6 +1834,54 @@ having nothing worth summarising.
 Every note in **both** groups still produces its JournalEntry and its web page.
 The difference is only whether a system Actor or Item is created as well.
 
+#### A system block is what makes a game document
+
+> **A note produces a system's Actor or Item only where it carries that
+> system's block.** A note carrying no block for any system produces no Actor
+> and no Item anywhere, whatever its packs declare.
+
+The block is not a place to put optional detail — it is the statement that this
+person or thing is meant to be played. Its absence is a statement too, and it is
+made silently: the note is passed over by the Actor and Item passes exactly as
+any note they do not own, with no finding.
+
+**Prose is untouched by this.** A body with content still compiles into one
+JournalEntry, one web page and one PDF page, however many blocks the note
+carries and whether or not it carries any; an empty body still compiles none of
+the three. So a note has three states, and each reaches the next by one edit in
+one file, with its address, its id, its index record and every link into it
+unchanged:
+
+| The note carries           | Produces                                       |
+| -------------------------- | ---------------------------------------------- |
+| no block, empty body       | an index record — a name that can be queried   |
+| no block, a written body   | a page, a PDF page and a JournalEntry          |
+| a block, a written body    | all of those, plus that system's Actor or Item |
+| two blocks, a written body | one document per system, and one of each other |
+
+Write the person; add a system block when someone will need a token. A setting's
+cast is mostly people nobody rolls dice against, and a note about one of them
+carries no block and occupies no slot in a compendium a referee browses.
+
+**A note carrying no document publishes no UUID for one.** Its address, its
+page and its documentation journal are published as they are for any other note,
+and the `foundry` entry that would name an Actor or an Item is absent — the same
+statement [`pack: none`](#the-pack-a-note-compiles-into) makes about a pack,
+made about a system.
+
+**A block for a system this package ships no pack for is an error.** The
+authored data would be discarded either way, so the build says so, once per note
+per system, naming the system and the document class:
+
+```
+assets/content/People/Aelric.md:7:1: error: carries a `hm3:` block, and no Actor pack in this package compiles hm3 documents, so the block is discarded — declare `system: hm3` on one of the `packs:`, or remove the block.
+```
+
+A pack declaring no `system:` is compiled by the fallback pass, which reads one
+system's block — so a systemless Actor pack serves that system and not every
+system a note might write. A package shipping for a second system declares
+`system:` on a pack of each class it compiles.
+
 That includes actors. A being producing its Actor and nothing else would be
 the one system-bearing note with no address at `none`, leaving a prose link
 naming it nowhere to land. It carries a documentation journal like every other

package/engine/actor-compiler.mjs

@@ -501,6 +501,18 @@ export class SystemActorCompiler extends BasePackCompiler {
      */
     static requiresSystemBlock = true;
 
+    /**
+     * 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 = "Actor";
+
     /**
      * The note-type → document-subtype map this pass compiles against.
      *

package/engine/base-compiler.mjs

@@ -183,13 +183,16 @@ export class BasePackCompiler {
 
     /**
      * 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
@@ -428,44 +431,56 @@ export class BasePackCompiler {
         );
     }
 
+    /**
+     * 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() {
+        return 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) {
-        if (!this.constructor.requiresSystemBlock || !this.packSystem) return true;
-        if (carriesSystemBlock(fm, this.packSystem)) return true;
-        // Another system's pack of this document type will claim it. A
-        // note carrying only `hm3:` routes here because this pack is the
-        // *default* of its document type, and defaults are declared per type
-        // rather than per system — but it is not an incomplete note, it is
-        // another pass's. The single-system case is untouched: with no second
-        // system declared there is nothing for this to find, and the error
-        // below still fires.
-        const claimant = (this.router?.systemsOfType?.(this.docType) ?? []).find(
-            (system) => system !== this.packSystem && carriesSystemBlock(fm, system),
-        );
-        if (claimant) return false;
-        const label = fm?.name?.full ?? fm?.shortcode ?? fm?.id ?? "this note";
-        throw new Error(
-            `${label} carries no \`${this.packSystem}:\` block, so it has no ` +
-                `${this.packSystem} data to compile — but it routes to pack ` +
-                `"${this.packName}", which declares \`system: ${this.packSystem}\`. ` +
-                `Add the block, or route the note to a pack of another system.`,
-        );
+        if (!this.constructor.requiresSystemBlock) return true;
+        return carriesSystemBlock(fm, this.system);
     }
 
     /**

package/engine/draft-notice.mjs

@@ -0,0 +1,175 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **What a draft note says about itself**, in one sentence, on every surface it
+ * reaches.
+ *
+ * A note tagged `draft` compiles, validates, publishes and resolves like any
+ * other. What separates it from a finished note is a judgement only its author
+ * holds — the content is not settled — and a reader who is not told assumes the
+ * opposite. So each surface states it where the reader cannot miss it: at the
+ * head of the entry, above the infobox and above the prose.
+ *
+ * **The words are the same everywhere and are stated once here.** A reader who
+ * meets the same note on a page, in a compendium and in the book should meet
+ * one statement, not three that agree approximately. {@link DRAFT_NOTICE} is
+ * that statement; every renderer below composes its own markup around it and
+ * changes none of it.
+ *
+ * **A label alone will not do.** "Draft" names the writing, so it reads as
+ * rough prose; what has to land is that the facts may change. The label and the
+ * sentence are one unit, and the sentence carries the meaning by itself — which
+ * is the floor each surface is built to, because each of them can lose
+ * everything around it.
+ *
+ * ## What each surface can rely on
+ *
+ * - **Foundry** renders a JournalEntry's own HTML inside a sheet, so the floor
+ *   is what a journal page carries with no module and no system stylesheet
+ *   loaded. Foundry draws a left rule on a `blockquote` in any application
+ *   window and bundles Font Awesome, so the rule and the mark are the host's
+ *   and nothing here ships CSS. The class is a hook for a package that wants
+ *   one, never a requirement.
+ * - **The book** sets Typst, where a glyph missing from the face is silent and
+ *   a consumer declaring no icon family is the normal case — see {@link
+ *   module:engine/content-icons}. So the mark is **drawn**, from two
+ *   primitives, and cannot become a box.
+ * - **An Actor's prose** lands in a system's own sheet, in a field the system
+ *   styles. It gets the same HTML the journal does; what it can rely on is the
+ *   sentence.
+ *
+ * @module
+ */
+
+import { isDraftNote } from "./note-vocabulary.mjs";
+
+/** 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 =
+    "This entry is unfinished. What it states may change, and nothing in it is settled.";
+
+/** 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";
+
+/**
+ * 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() {
+    return (
+        `<blockquote class="${DRAFT_NOTICE_CLASS}">` +
+        `<p><i class="fa-solid ${DRAFT_NOTICE_ICON}" aria-hidden="true"></i> ` +
+        `<strong>${DRAFT_NOTICE_LABEL}</strong> ${DRAFT_NOTICE}</p>` +
+        `</blockquote>`
+    );
+}
+
+/**
+ * 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) {
+    return isDraftNote(fm) ? draftNoticeHtml() : "";
+}
+
+/**
+ * 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, html) {
+    const notice = draftNoticeFor(fm);
+    if (!notice) return html;
+    return html ? `${notice}\n${html}` : notice;
+}
+
+/**
+ * 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() {
+    return (
+        `#let ${BOOK_DRAFT_NOTICE}(label, body) = block(\n` +
+        "  width: 100%, above: 0.55em, below: 0.75em, breakable: false,\n" +
+        "  inset: (left: 0.7em, top: 0.35em, bottom: 0.35em),\n" +
+        "  stroke: (left: 1.6pt + book-faint))[\n" +
+        "  #set par(justify: false, first-line-indent: 0em)\n" +
+        "  #set text(size: 8.6pt, fill: book-faint)\n" +
+        "  #box(baseline: 0.18em, circle(radius: 0.42em, stroke: 0.6pt + book-faint)[\n" +
+        '    #align(center + horizon)[#text(size: 6.4pt, weight: "bold")[!]]\n' +
+        "  ])\n" +
+        "  #h(0.4em)\n" +
+        '  #text(weight: "bold")[#label]\n' +
+        "  #h(0.25em)\n" +
+        "  #body\n" +
+        "]"
+    );
+}
+
+/**
+ * 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() {
+    return `#${BOOK_DRAFT_NOTICE}[${DRAFT_NOTICE_LABEL}][${DRAFT_NOTICE}]`;
+}