@heroiclands/package-build 22.6.0 → 22.7.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @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

package/CONTENT.md

@@ -1113,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.

package/docs/content-format.md

@@ -320,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
@@ -1677,11 +1712,11 @@ 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 —

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}]`;
+}

package/engine/index.mjs

@@ -87,6 +87,9 @@ export * as noteVocabulary from "./note-vocabulary.mjs";
 /** The three states of a note — stub, draft, full — and the empty body they rest on. */
 export * as noteState from "./note-state.mjs";
 
+/** What a draft note says about itself, in one sentence, on every surface. */
+export * as draftNotice from "./draft-notice.mjs";
+
 /** Whether every empty body is a stub on purpose, and how finished a tree is. */
 export * as stubLint from "./stub-lint.mjs";
 

package/engine/item-docs.mjs

@@ -64,10 +64,10 @@ export { itemTypes };
  * 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
@@ -76,8 +76,9 @@ export { itemTypes };
  * 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).
@@ -93,8 +94,8 @@ export function docEntryTypes() {
  * 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) {
     // Through {@link currentType}, because the set is derived from the item

package/engine/journals.mjs

@@ -18,14 +18,17 @@
  * The content root (`contentBase`) is walked recursively; any `.md` file
  * whose frontmatter declares either `type: doc` or a
  * **doc-carrying type** ({@link sohl.utils.packs.docEntryTypes} — every item
- * type, plus `macro`) is compiled into one JournalEntry document. Each note's
+ * type, every actor type, every map type, plus `macro`) is compiled into one
+ * JournalEntry document. Each note's
  * body is split on top-level H1 headings; the optional content before the
  * first H1 becomes a lead page, and each subsequent H1 starts a new page named
  * after its heading text. All page bodies are rendered to HTML.
  *
  * A doc-carrying note compiles into that document's **documentation** — the
- * same prose and pages, filed in the same folder as the document itself, which
- * keeps only a pointer to it. See `item-docs.mjs` for why, and for the ids the
+ * same prose and pages, filed in the same folder as the document itself. An
+ * item keeps only a pointer to it; an actor keeps its own inline prose as
+ * well, because the indirection an item pays for is bought by embedding one
+ * item across hundreds of beings and an actor is singular. See `item-docs.mjs` for why, and for the ids the
  * two passes agree on. A macro note's `{#script}` page is compiled here like
  * any other: the macro pass reads the same page independently, and withholds
  * nothing from the journal.
@@ -56,6 +59,7 @@ import { noteInfoboxes } from "./infobox-registry.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { JOURNAL_TYPES } from "./ids.mjs";
 import { journalHasContent } from "./note-state.mjs";
+import { draftNoticeFor } from "./draft-notice.mjs";
 
 /**
  * Splits a markdown body into pages by top-level H1 headings. Fenced
@@ -287,6 +291,11 @@ export function buildPages(rawPages, entryId, noteName) {
  *   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({
@@ -298,12 +307,16 @@ export function buildJournalEntry({
     flags,
     stats = defaultStats(),
     infobox = "",
+    notice = "",
 }) {
     const rawPages = splitPages(markdown, leadName);
     const pages = buildPages(rawPages, id, name);
     if (infobox.trim() && pages.length) {
         pages[0].text.content = `${infobox}\n${pages[0].text.content}`;
     }
+    if (notice.trim() && pages.length) {
+        pages[0].text.content = `${notice}\n${pages[0].text.content}`;
+    }
     return {
         name,
         pages,
@@ -407,7 +420,7 @@ export class Journals extends BasePackCompiler {
      * Compile one note into a JournalEntry.
      *
      * A `doc` note becomes the entry its frontmatter describes. A
-     * **doc-carrying note** — every item note, and every macro note — becomes
+     * **doc-carrying note** — every item, actor, map and macro note — becomes
      * that document's documentation instead: the same prose, the same pages,
      * in the same folder, under an id derived from the note's, so the pointer
      * the items pass wrote resolves to it (see
@@ -458,6 +471,12 @@ export class Journals extends BasePackCompiler {
             name,
             markdown,
             infobox: infoboxesToHtml(boxes, { link: linkToUuid }),
+            // Whether the entry is settled, asked of the tag through the one
+            // reader of it. This sits here rather than in `buildJournalEntry`
+            // for the reason `skipNote` runs first: a note with no prose
+            // compiles into nothing, and a notice composed before that test
+            // would be content enough to give it an entry.
+            notice: draftNoticeFor(fm),
             // A doc-carrying note's lead page is the document itself, not an
             // "Introduction" — see {@link splitPages}.
             leadName: ownsDoc ? name : undefined,

package/engine/pdf-build.mjs

@@ -112,6 +112,8 @@ import {
     renderBook,
     resolveDanglingLabels,
 } from "./pdf-render.mjs";
+import { draftNoticeTypst } from "./draft-notice.mjs";
+import { isDraftNote } from "./note-vocabulary.mjs";
 import { infoboxTypstPreamble, infoboxesToTypst, linkToTypst } from "./infobox-render.mjs";
 import { noteInfoboxes } from "./infobox-registry.mjs";
 import { resolveIconGlyphs } from "./pdf-fonts.mjs";
@@ -540,7 +542,12 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
         const panel = infoboxesToTypst(boxes, {
             link: (value) => linkToTypst(value, plan.links, labelFor),
         });
-        return panel ? `${panel}\n\n${prose}` : prose;
+        // Whether the entry is settled comes before anything it says: the
+        // notice leads the leaf, ahead of the panel, which is the position it
+        // holds on every other surface.
+        const notice = isDraftNote(page.fm) ? draftNoticeTypst() : "";
+        const parts = [notice, panel, prose].filter((part) => part);
+        return parts.join("\n\n");
     };
 
     const bodies = new Map();

package/engine/pdf-render.mjs

@@ -63,6 +63,7 @@
 
 import MarkdownIt from "markdown-it";
 
+import { bookDraftNoticePreamble } from "./draft-notice.mjs";
 import { iconPlugin, ICON_PATTERN } from "./content-icons.mjs";
 import { IMAGE_CLASSES, IMAGE_FLOATS, imagePlugin } from "./content-images.mjs";
 import { slugify } from "./content-slug.mjs";
@@ -882,6 +883,11 @@ export function bookTypstPreamble() {
             "    ]\n" +
             "  ]\n" +
             "}",
+        // A statement about the entry rather than about its subject, set in
+        // the running face at the head of the leaf. The mark is drawn from two
+        // primitives rather than set from a face: a consumer declares its icon
+        // families or declares none, and a glyph the face lacks is silent here.
+        bookDraftNoticePreamble(),
         "#let book-epigraph(body) = {\n" +
             "  v(0.42cm)\n" +
             "  align(center)[\n" +

package/hm3/actors.mjs

@@ -53,6 +53,7 @@ import { resolveName } from "../engine/helpers.mjs";
 import { buildFromFields, retiredTopLevelKey, STRING } from "../engine/field-spec.mjs";
 import { SystemActorCompiler } from "../engine/actor-compiler.mjs";
 import { renderSection } from "../engine/anchored-sections.mjs";
+import { withDraftNotice } from "../engine/draft-notice.mjs";
 import { documentSubtype } from "../engine/document-subtypes.mjs";
 import { HM3_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 import { templateFlags } from "./template-priority.mjs";
@@ -348,7 +349,10 @@ export class Hm3Actors extends SystemActorCompiler {
             // `system.portrait` is not: a being's portrait is the lead image of
             // its `{#appearance}` section, which is the markup below.
             description: renderSection(body || "", "appearance"),
-            biography: renderSection(body || "", "dossier"),
+            // `biography` is this system's dossier: the two are paired by the
+            // authored section each reads, not by their names, so the notice
+            // lands on the same prose here as it does under SoHL.
+            biography: withDraftNotice(fm, renderSection(body || "", "dossier")),
             ...buildFromFields(ACTOR_FIELDS, reports)(fm),
             // Declared on `character` alone, so written there alone — see the
             // module note.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.6.0",
+    "version": "22.7.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/sohl/actors.mjs

@@ -49,6 +49,7 @@
 import { sohlField, resolveName, systemTemplatePriority, folderField } from "../engine/helpers.mjs";
 import { openingMasteryLevel } from "./skill-base.mjs";
 import { SystemActorCompiler, renderSection } from "../engine/actor-compiler.mjs";
+import { withDraftNotice } from "../engine/draft-notice.mjs";
 // Which Foundry Actor subtype a note's `type` compiles into. Looked up in the
 // system's declared map, never inferred from the type itself.
 import { documentSubtype } from "../engine/document-subtypes.mjs";
@@ -347,7 +348,11 @@ export class Actors extends SystemActorCompiler {
             // key that used to declare one is not a key. With no authored
             // source left, the field keeps the schema's own initial.
             appearance: renderSection(body || "", "appearance"),
-            dossier: renderSection(body || "", "dossier"),
+            // One document says it once. `dossier` is the field that carries
+            // an unsettled entry's notice, and `appearance` carries none —
+            // the print sheet draws both blocks in turn, so a notice on each
+            // would be read twice on one page.
+            dossier: withDraftNotice(fm, renderSection(body || "", "dossier")),
         };
 
         // Fill `system.body` (+ the base-actor movement fields) from the being's

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/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/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.