@heroiclands/package-build 22.12.1 → 22.12.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @heroiclands/package-build
 
+## 22.12.2
+
+### Patch Changes
+
+**Content**
+
+- GM passages in notes appear as secret sections in Foundry journals, expandable spoilers on the web, and labelled notes in books.
+
 ## 22.12.1
 
 ### Patch Changes

package/bin/content-build.mjs

@@ -1627,6 +1627,9 @@ function siteCommand() {
                         message: e.reason,
                     });
                 }
+                for (const e of result.secretErrors) {
+                    emitDiagnostic({ ...e, severity: "error" });
+                }
                 // Reported the way the pack build reports the very same
                 // finding: `file:line:column: error: message`, path first, and
                 // the message from the shared table, not a
@@ -1663,6 +1666,7 @@ function siteCommand() {
                 }
                 if (
                     result.tableErrors.length ||
+                    result.secretErrors.length ||
                     result.wikiErrors.length ||
                     result.imageErrors.length
                 ) {

package/docs/api.md

@@ -1012,6 +1012,7 @@ Shared helpers for the pack compilers in `packages/content-build/`. The HeroicLa
 | Export                    | Signature                                                                                                   | Returns                                                                                                                                                                                                                                 | Use it when                                                                                                                                                                                          |
 | ------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `md`                      | `const md`                                                                                                  | —                                                                                                                                                                                                                                       | The markdown renderer every surface shares.                                                                                                                                                          |
+| `renderFoundryMarkdown`   | `function renderFoundryMarkdown(body)`                                                                      | `string` — HTML with secret sections for GM passages.                                                                                                                                                                                   | Rendering a note body for a Foundry document.                                                                                                                                                        |
 | `parseMarkdownFile`       | `function parseMarkdownFile(filePath)`                                                                      | —                                                                                                                                                                                                                                       | Parses a markdown file with YAML frontmatter.                                                                                                                                                        |
 | `assertStatedScope`       | `function assertStatedScope(skipDirectories, who)`                                                          | {void}                                                                                                                                                                                                                                  | Refuse a corpus read whose scope its caller did not state.                                                                                                                                           |
 | `assertSuppliedCorpus`    | `function assertSuppliedCorpus(records, who)`                                                               | {void}                                                                                                                                                                                                                                  | Refuse a corpus read whose records its caller did not supply.                                                                                                                                        |

package/docs/content-format.md

@@ -2418,15 +2418,17 @@ This is secret text
 :::
 ```
 
-A fenced off area of text may be marked as secret, indicating that the text will be treated as secret text. In FoundryVTT, this will be achieved with
+Use a whole-line `:::secret` opener and a whole-line `:::` closer to mark a GM passage. Markdown inside the block, including links and emphasis, renders normally. Keep the fences outside code blocks and close each one before starting another. An unclosed or nested block is a build error at the source line.
+
+In FoundryVTT, the passage is a secret section visible to the GM and owners of the journal:
 
 ```html
-<section class="secret">
+<section class="secret" id="secret-example">
   <p>This is secret text</p>
 </section>
 ```
 
-On webpages, this will be achieved with the use of
+On webpages, the passage appears as a collapsed spoiler that any reader can open:
 
 ```html
 <details>
@@ -2435,6 +2437,8 @@ On webpages, this will be achieved with the use of
 </details>
 ```
 
+In books, the passage is visible under a **GM note** label. A printed page has no reader permissions or interactive disclosure control.
+
 #### Actors
 
 All actor types, including being and vehicle, have their entire markdown section processed as normal.

package/engine/anchored-sections.mjs

@@ -29,7 +29,7 @@
  * @module
  */
 
-import { md } from "./helpers.mjs";
+import { renderFoundryMarkdown } from "./helpers.mjs";
 
 /**
  * Extract the body of an H1 section whose heading carries the explicit
@@ -79,5 +79,5 @@ export function extractAnchorSection(body, anchorId) {
  */
 export function renderSection(body, anchorId) {
     const slice = extractAnchorSection(body, anchorId);
-    return slice ? md.render(slice) : "";
+    return slice ? renderFoundryMarkdown(slice) : "";
 }

package/engine/base-compiler.mjs

@@ -62,6 +62,7 @@
  */
 
 import { authoredFrontmatter } from "./index-records.mjs";
+import { renderSecretBlocks } from "./content-secrets.mjs";
 import { cloneAddressState } from "./address-values.mjs";
 import fs from "fs";
 import path from "path";
@@ -620,6 +621,18 @@ export class BasePackCompiler {
      *   that does not convert.
      */
     convertBody(fm, body) {
+        const secretError = renderSecretBlocks(body, "book").errors[0];
+        if (secretError) {
+            const error = new Error(secretError.message);
+            error.position = {
+                line: (this.currentNote?.bodyLine ?? 1) + secretError.line - 1,
+                column:
+                    secretError.line === 1 ?
+                        (this.currentNote?.bodyColumn ?? 1)
+                    :   secretError.column,
+            };
+            throw error;
+        }
         if (!this.constructor.convertsWikilinks) return body;
         const name = resolveName(fm);
         const { absPath, bodyLine, bodyColumn } = this.currentNote ?? {};

package/engine/bundles.mjs

@@ -72,7 +72,7 @@ import { contentPackage } from "./content-package.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
-import { folderField, md, resolveName } from "./helpers.mjs";
+import { folderField, renderFoundryMarkdown, resolveName } from "./helpers.mjs";
 import { packForType } from "./ids.mjs";
 import { readQualifier } from "./wikilinks.mjs";
 
@@ -322,7 +322,7 @@ export class Bundles extends BasePackCompiler {
             // Foundry renders on the import card. That is why a bundle earns no
             // separate documentation journal the way an item does: the document
             // it compiles into already has somewhere to put the prose.
-            description: markdown.trim() ? md.render(markdown) : "",
+            description: markdown.trim() ? renderFoundryMarkdown(markdown) : "",
             folder: this.folderResolver(authoredFolder, { isAddress: folderIsAddress }),
             flags: fm.flags,
             stats: this.stats,

package/engine/content-secrets.mjs

@@ -0,0 +1,110 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import crypto from "node:crypto";
+import markdownit from "markdown-it";
+
+const webMarkdown = markdownit({ html: true });
+
+/**
+ * Render whole-line `:::secret` blocks for one publishing surface.
+ * The source line of each syntax error is relative to the supplied body.
+ *
+ * @param {string} source - Markdown containing secret blocks.
+ * @param {"foundry"|"web"|"book"} target - Publishing surface.
+ * @param {(markdown: string) => string} [renderMarkdown] - Foundry's configured renderer.
+ * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function renderSecretBlocks(
+    source,
+    target,
+    renderMarkdown = webMarkdown.render.bind(webMarkdown),
+) {
+    const lines = String(source ?? "").split("\n");
+    const result = [];
+    const errors = [];
+    let opening = -1;
+    let body = [];
+    let codeFence = null;
+
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const fence = line.match(/^ {0,3}(`{3,}|~{3,})/);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
+                codeFence = null;
+            }
+            if (opening >= 0) body.push(line);
+            else result.push(line);
+            continue;
+        }
+        if (fence) {
+            codeFence = fence[1];
+            if (opening >= 0) body.push(line);
+            else result.push(line);
+            continue;
+        }
+        if (/^:::secret[ \t]*$/.test(line)) {
+            if (opening >= 0) {
+                errors.push({
+                    line: index + 1,
+                    column: 1,
+                    message: "nested secret blocks are not supported",
+                });
+                body.push(line);
+            } else {
+                opening = index;
+                body = [];
+            }
+            continue;
+        }
+        if (/^:::[ \t]*$/.test(line)) {
+            if (opening < 0) {
+                errors.push({
+                    line: index + 1,
+                    column: 1,
+                    message: "secret block has no opening :::secret line",
+                });
+                result.push(line);
+                continue;
+            }
+            const inner = body.join("\n").trim();
+            if (target === "book") {
+                result.push("", "**GM note**", "", inner, "");
+            } else {
+                const html = renderMarkdown(inner).trim();
+                if (target === "foundry") {
+                    const id = crypto
+                        .createHash("sha256")
+                        .update(`${opening}:${inner}`)
+                        .digest("hex")
+                        .slice(0, 12);
+                    result.push(
+                        "",
+                        `<section class="secret" id="secret-${id}">`,
+                        html,
+                        "</section>",
+                        "",
+                    );
+                } else {
+                    result.push("", "<details><summary>Spoiler</summary>", html, "</details>", "");
+                }
+            }
+            opening = -1;
+            body = [];
+            continue;
+        }
+        if (opening >= 0) body.push(line);
+        else result.push(line);
+    }
+    if (opening >= 0) {
+        errors.push({
+            line: opening + 1,
+            column: 1,
+            message: "secret block needs a closing ::: line",
+        });
+        result.push(":::secret", ...body);
+    }
+    return { markdown: result.join("\n"), errors };
+}

package/engine/helpers.mjs

@@ -62,6 +62,7 @@ import { linkFindingMessage } from "./wikilink-syntax.mjs";
 // from there rather than respelt, so the tag and its one reader cannot drift.
 import { isDraftNote } from "./note-vocabulary.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { renderSecretBlocks } from "./content-secrets.mjs";
 import { positionInBody } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
 // registry can import them without reaching back through this one.
@@ -125,6 +126,12 @@ export const md = markdownit({ html: true })
         }),
     );
 
+/** Render a note body with Foundry's secret section markup. */
+export function renderFoundryMarkdown(body) {
+    const { markdown } = renderSecretBlocks(body, "foundry", (inner) => md.render(inner));
+    return md.render(markdown);
+}
+
 /**
  * Parses a markdown file with YAML frontmatter.
  *
@@ -165,7 +172,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
     }
     const raw = fmMatch[2];
     const body = raw.trim();
-    const description = body ? md.render(body) : "";
+    const description = body ? renderFoundryMarkdown(body) : "";
     // Where the trimmed body starts in the *file*, so an offset within it can
     // be reported as a file position. The frontmatter's lines and the
     // blank lines `trim()` removes both sit in between, and the trim can take

package/engine/journals.mjs

@@ -51,7 +51,14 @@
 
 import log from "loglevel";
 
-import { sohlField, makeId, resolveName, defaultStats, md, folderField } from "./helpers.mjs";
+import {
+    sohlField,
+    makeId,
+    resolveName,
+    defaultStats,
+    renderFoundryMarkdown,
+    folderField,
+} from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { anchorPageId, resolveReference } from "./wikilinks.mjs";
 import { infoboxesToHtml, linkToUuid } from "./infobox-render.mjs";
@@ -83,6 +90,7 @@ export function splitPages(body, leadName = "Introduction") {
     const beforeFirstH1 = [];
     let current = null;
     let inCodeBlock = false;
+    let inSecret = false;
 
     const closeCurrent = () => {
         if (!current) return;
@@ -99,11 +107,14 @@ export function splitPages(body, leadName = "Introduction") {
         if (line.trim().startsWith("```")) {
             inCodeBlock = !inCodeBlock;
         }
+        if (!inCodeBlock && /^:::secret[ \t]*$/.test(line)) inSecret = true;
+        else if (!inCodeBlock && /^:::[ \t]*$/.test(line)) inSecret = false;
 
         // An H1 starts a page, as does any heading carrying an `{#slug}`
         // anchor: a Foundry UUID can only address a page, so a linkable
         // section has to be one.
-        const headingMatch = !inCodeBlock ? line.match(/^\s*(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
+        const headingMatch =
+            !inCodeBlock && !inSecret ? line.match(/^\s*(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
         const rawHeading = headingMatch?.[2]?.trim();
         const anchorMatch = rawHeading?.match(/^(.*?)\s*\{#([^}]+)\}\s*$/);
         const startsPage = headingMatch && (headingMatch[1].length === 1 || anchorMatch);
@@ -255,7 +266,7 @@ export function buildPages(rawPages, entryId, noteName) {
             title: { show: true, level: page.level ?? 1 },
             text: {
                 format: 1,
-                content: page.markdown ? md.render(page.markdown) : "",
+                content: page.markdown ? renderFoundryMarkdown(page.markdown) : "",
             },
             _key: `!journal.pages!${entryId}.${pageId}`,
         };

package/engine/pdf-build.mjs

@@ -102,6 +102,7 @@ import { resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { linkFindingMessage } from "./wikilink-syntax.mjs";
 import { assetAddressIndex } from "./art-fields.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { renderSecretBlocks } from "./content-secrets.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { imageSourcesIn } from "./content-images.mjs";
 import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
@@ -523,8 +524,18 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                 message: err.message ?? (err.reason ? linkFindingMessage(err) : String(err)),
             });
         }
-        stageImages(resolvedBody, page.file);
-        const prose = markdownToTypst(resolvedBody, {
+        const secrets = renderSecretBlocks(resolvedBody, "book");
+        for (const error of renderSecretBlocks(page.body, "book").errors) {
+            findings.push({
+                file: page.file,
+                line: (page.bodyLine ?? 1) + error.line - 1,
+                column: error.column,
+                severity: "error",
+                message: error.message,
+            });
+        }
+        stageImages(secrets.markdown, page.file);
+        const prose = markdownToTypst(secrets.markdown, {
             md,
             links: plan.links,
             glyphs,

package/engine/site-build.mjs

@@ -61,6 +61,7 @@ import matter from "gray-matter";
 import { addressSlug } from "./content-address.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { renderSecretBlocks } from "./content-secrets.mjs";
 import { renderImageFigures } from "./content-images.mjs";
 import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
 import { buildSiteIndex, resolveInfoboxRef, wikiContext } from "./site-index.mjs";
@@ -140,8 +141,10 @@ function siteCorpusFiles(contentBase, ctx) {
  */
 function readNote(file, ctx) {
     let parsed;
+    let source;
     try {
-        parsed = matter(fs.readFileSync(file, "utf8"));
+        source = fs.readFileSync(file, "utf8");
+        parsed = matter(source);
     } catch {
         return null;
     }
@@ -150,7 +153,11 @@ function readNote(file, ctx) {
         package: ctx.contentPackage ?? ctx.config?.contentPackage,
     };
     try {
-        return { fm: decodeNoteAddresses(parsed.data, context), body: parsed.content };
+        return {
+            fm: decodeNoteAddresses(parsed.data, context),
+            body: parsed.content,
+            bodyLine: source.slice(0, source.length - parsed.content.length).split("\n").length,
+        };
     } catch (error) {
         const position = positionOfYamlPath(parsed.matter, error.keyPath ?? [], {
             key: error.addressKey,
@@ -202,7 +209,7 @@ export function collectContentPages(contentBase, ctx) {
         const note = readNote(file, ctx);
         if (!note) continue;
         applyComputedBeingAge(note.fm, present);
-        const { fm, body } = note;
+        const { fm, body, bodyLine } = note;
         // The configuration's, never a note's: `package:` is retired, so every
         // note in the tree belongs to the package this repository compiles.
         const pkg = ctx.contentPackage;
@@ -249,6 +256,7 @@ export function collectContentPages(contentBase, ctx) {
             // — reads one configured value and never frontmatter.
             pkg,
             body,
+            bodyLine,
             name,
             slug,
             base,
@@ -734,6 +742,7 @@ export function renderPages(pages, options) {
     });
 
     const tableErrors = [];
+    const secretErrors = [];
     const wikiErrors = [];
     const imageErrors = [];
     const byKind = {};
@@ -847,7 +856,17 @@ export function renderPages(pages, options) {
         tableErrors.push(...errors);
 
         const data = pageFrontmatter(page, { decorate, webSrc, artSrc });
-        rendered.push({ page, body: protectCode(body, resolve), data });
+        const resolvedBody = protectCode(body, resolve);
+        const secrets = renderSecretBlocks(resolvedBody, "web");
+        for (const error of renderSecretBlocks(page.body, "book").errors) {
+            secretErrors.push({
+                file: page.file,
+                line: (page.bodyLine ?? 1) + error.line - 1,
+                column: error.column,
+                message: error.message,
+            });
+        }
+        rendered.push({ page, body: secrets.markdown, data });
         // A resolved target with no URL is a pack-only package's address:
         // real, and nowhere on the web, so not an edge.
         for (const hit of resolved) {
@@ -885,6 +904,7 @@ export function renderPages(pages, options) {
         written: pages.length,
         byKind,
         tableErrors,
+        secretErrors,
         wikiErrors,
         imageErrors,
         related,
@@ -1044,6 +1064,7 @@ export function buildSite({ config, sqlTables, locate } = {}) {
             gates: { ...emptyGates(), homepages: homepageFindings },
             manifests: null,
             tableErrors: [],
+            secretErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1063,6 +1084,7 @@ export function buildSite({ config, sqlTables, locate } = {}) {
             gates: emptyGates(),
             manifests: null,
             tableErrors: [],
+            secretErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1108,6 +1130,7 @@ export function buildSite({ config, sqlTables, locate } = {}) {
             gates,
             stats: null,
             tableErrors: [],
+            secretErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1175,6 +1198,7 @@ export function buildSite({ config, sqlTables, locate } = {}) {
     return {
         gates,
         tableErrors: rendered.tableErrors,
+        secretErrors: rendered.secretErrors,
         wikiErrors: rendered.wikiErrors,
         imageErrors: rendered.imageErrors,
         mapFindings: drawn.findings,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.12.1",
+    "version": "22.12.2",
     "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/types/engine/content-secrets.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Render whole-line `:::secret` blocks for one publishing surface.
+ * The source line of each syntax error is relative to the supplied body.
+ *
+ * @param {string} source - Markdown containing secret blocks.
+ * @param {"foundry"|"web"|"book"} target - Publishing surface.
+ * @param {(markdown: string) => string} [renderMarkdown] - Foundry's configured renderer.
+ * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function renderSecretBlocks(source: string, target: "foundry" | "web" | "book", renderMarkdown?: (markdown: string) => string): {
+    markdown: string;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};

package/types/engine/helpers.d.mts

@@ -1,3 +1,5 @@
+/** Render a note body with Foundry's secret section markup. */
+export function renderFoundryMarkdown(body: any): string;
 /**
  * Parses a markdown file with YAML frontmatter.
  *