@heroiclands/package-build 22.12.1 → 22.12.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @heroiclands/package-build
 
+## 22.12.3
+
+### Patch Changes
+
+- Content authors can find notes by name, alias, tag, shortcode, or Address and follow references from an LSP-capable editor.
+- Editor reference search works without ripgrep installed.
+
+## 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/README.md

@@ -14,6 +14,9 @@ The content half is documented separately in **[CONTENT.md](CONTENT.md)** — th
 note format, the pack pipeline, and the configuration contract a content tree
 declares itself with.
 
+Editor navigation through the content index is described in the
+[content language server guide](docs/content-language-server.md).
+
 ## Install
 
 ```

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/bin/heroiclands-content-language-server.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { runLanguageServer } from "../engine/content-language-server.mjs";
+
+runLanguageServer();

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

@@ -1,11 +1,14 @@
 # Command reference
 
-`@heroiclands/package-build` ships two binaries. `package-build` is the
+`@heroiclands/package-build` ships two build binaries. `package-build` is the
 packaging half — clean, stage, check, package, deploy, run a Foundry
 container, drive the end-to-end suite. `content-build` is the content half —
 compile a note tree into compendium packs, check it, publish it as a site or a
 book, and manage the caches a build resolves other packages through.
 
+The package also ships `heroiclands-content-language-server`, a stdio editor
+service described in the [content language server guide](content-language-server.md).
+
 Both read `package-build.config.yaml` from the repository root — see
 [Configuration](configuration.md) for every key. Neither reads it for
 `--version` or `--help`: those two answer in a directory with no
@@ -21,7 +24,7 @@ says so under **OPTIONS** rather than omitting the section.
 
 **Every finding is `file:line:column: severity: message`**, the path starting
 the line — the diagnostic contract this package's own build tooling emits and
-that both binaries' content-side commands use for anything found in a
+that both build binaries' content-side commands use for anything found in a
 specific file. A field that cannot be known is dropped rather than guessed:
 `file:line:` when the column means nothing, `file:` when only the file is
 known. See [Diagnostics](diagnostics.md) for the full contract.

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/docs/content-language-server.md

@@ -0,0 +1,25 @@
+# Content language server
+
+`heroiclands-content-language-server` provides editor navigation for Markdown notes in a HeroicLands content project. It is a stdio Language Server Protocol process; an editor starts it from the project root. The command uses the same `package-build.config.yaml` and Address rules as `content-build`.
+
+Build the content index in the project before starting navigation:
+
+```sh
+npx content-build content-index
+```
+
+The generated JSONL file under the configured `paths.contentIndex` is the source for note names, aliases, tags, shortcodes, Addresses, and destinations. Search covers the current project. Search and destinations reflect the saved index, so run the index command after changing note metadata. The language server reads a completed replacement index on its next request. An editor's unsaved buffer text is used to identify the Address at the cursor, but it does not add search results.
+
+| LSP request               | Behavior                                                                                                                     |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `textDocument/definition` | Follows an Address or wikilink to the indexed note. An anchor lands on its indexed line.                                     |
+| `workspace/symbol`        | Finds notes by name, alias, ASCII name, shortcode, or Address. `tag:myth` searches tags. One result appears per source note. |
+| `textDocument/references` | Finds authored wikilinks, embeds, and declared frontmatter Address values or keys. Ordinary prose is excluded.               |
+
+The server reports a missing index with the `content-build content-index` command. Reference search scans Markdown notes in the configured content tree. The server writes only LSP messages to stdout, and it uses UTF-16 positions as required by the default LSP position encoding.
+
+## Editor integration
+
+The [HeroicLands Emacs package](https://github.com/HeroicLands/heroiclands-emacs) connects this command through Eglot in content Markdown buffers. Eglot maps `M-.` to definition, `C-M-.` to workspace search, `M-?` to references, and `M-,` to the Xref location stack.
+
+An editor other than Emacs starts the executable from the package root and associates it with Markdown notes under the configured content directory. The process handles `initialize`, `shutdown`, `exit`, full and incremental document synchronization, definition, references, and workspace symbols. It does not advertise completion, diagnostics, rename, or document symbols.

package/docs/getting-started.md

@@ -132,9 +132,10 @@ repository.
 npm install --save-dev @heroiclands/package-build
 ```
 
-That installs two binaries into `node_modules/.bin`: `package-build`, the
-packaging half, and `content-build`, the content half. Every command below is
-one of those two. Run them through `npx`, or wire them into npm scripts as
+That installs `package-build`, the packaging half, and `content-build`, the
+content half, into `node_modules/.bin`. It also installs the optional
+`heroiclands-content-language-server` for editor navigation. Every build command
+below uses one of the first two binaries. Run them through `npx`, or wire them into npm scripts as
 [`project-setup.md`](project-setup.md) describes.
 
 **How it worked:** `npx package-build --version` prints the installed version.

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-language-server.mjs

@@ -0,0 +1,439 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import YAML from "yaml";
+import { parseAddress, renderAddress } from "./address.mjs";
+import { addressPositions } from "./note-addresses.mjs";
+import { parseWikilink, WIKILINK } from "./wikilink-syntax.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+import { noteFile } from "./index-records.mjs";
+import { NOTE_VOCABULARY } from "./note-vocabulary.mjs";
+import { metadataFileName } from "./packages.mjs";
+import { matchAllOutsideCode } from "./code-fences.mjs";
+import { embedsIn, EMBED_DEFAULT_TYPE } from "./content-embeds.mjs";
+
+const EMPTY_RANGE = { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } };
+
+/** Return an LSP position for a UTF-16 offset in TEXT. */
+function positionAt(text, offset) {
+    const before = text.slice(0, offset);
+    const line = before.split("\n").length - 1;
+    const lastNewline = before.lastIndexOf("\n");
+    return { line, character: offset - lastNewline - 1 };
+}
+
+/** Return a UTF-16 offset for an LSP position in TEXT. */
+function offsetAt(text, position) {
+    const lines = text.split("\n");
+    if (position.line < 0 || position.line >= lines.length) return -1;
+    let offset = 0;
+    for (let i = 0; i < position.line; i++) offset += lines[i].length + 1;
+    return offset + Math.min(position.character, lines[position.line].length);
+}
+
+function location(file, text, start, end) {
+    return {
+        uri: pathToFileURL(file).href,
+        range: { start: positionAt(text, start), end: positionAt(text, end) },
+    };
+}
+
+function noteName(record) {
+    return typeof record.name === "string" ? record.name : (record.name?.full ?? record.shortcode);
+}
+
+/** An index read from the package's configured content tree. */
+export class ContentWorkspace {
+    constructor(config = loadPackConfig()) {
+        this.config = config;
+        this.contentRoot = config.paths.content;
+        this.indexFile = path.join(
+            config.paths.contentIndex,
+            metadataFileName(config.contentPackage),
+        );
+        this.indexState = "";
+        this.records = [];
+        this.byAddress = new Map();
+        this.byFile = new Map();
+        this.types = new Set(Object.keys(NOTE_VOCABULARY));
+        this.documents = new Map();
+    }
+
+    refresh() {
+        let stat;
+        try {
+            stat = fs.statSync(this.indexFile);
+        } catch {
+            this.indexState = "";
+            this.records = [];
+            this.byAddress.clear();
+            this.byFile.clear();
+            return false;
+        }
+        const state = `${stat.mtimeMs}:${stat.size}`;
+        if (state === this.indexState) return true;
+        const records = fs
+            .readFileSync(this.indexFile, "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+        const byAddress = new Map();
+        const byFile = new Map();
+        const types = new Set(Object.keys(NOTE_VOCABULARY));
+        for (const record of records) {
+            if (record.type) types.add(record.type);
+            if (record.address?.canonical)
+                byAddress.set(record.address.canonical.toLowerCase(), record);
+            if (record.file?.path) {
+                const file = noteFile(this.contentRoot, record);
+                if (!byFile.has(file)) byFile.set(file, record);
+            }
+        }
+        this.records = records;
+        this.byAddress = byAddress;
+        this.byFile = byFile;
+        this.types = types;
+        this.indexState = state;
+        return true;
+    }
+
+    requireIndex() {
+        if (!this.refresh())
+            throw new Error(
+                `No content index at ${this.indexFile}; run content-build content-index`,
+            );
+    }
+
+    fileFor(record) {
+        if (record.file?.path) return noteFile(this.contentRoot, record);
+        if (record.asset?.path)
+            return path.join(this.config.paths.assets, ...record.asset.path.split("/"));
+        return null;
+    }
+
+    text(uri) {
+        if (this.documents.has(uri)) return this.documents.get(uri);
+        try {
+            return fs.readFileSync(fileURLToPath(uri), "utf8");
+        } catch {
+            return null;
+        }
+    }
+
+    /** Resolve a written Address using the same tuple grammar as the build. */
+    resolve(value, defaults = {}) {
+        const tuple = parseAddress(value, {
+            package: this.config.contentPackage,
+            system: "none",
+            types: this.types,
+            packages: new Set([this.config.contentPackage]),
+            ...defaults,
+        });
+        if (tuple.reason) return null;
+        return this.byAddress.get(renderAddress(tuple)) ?? null;
+    }
+
+    /** Link and declared frontmatter targets, with exact source ranges. */
+    referencesInText(text, file) {
+        const found = [];
+        const bodyStart = text.match(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/)?.[0].length ?? 0;
+        const linkText = text.slice(bodyStart);
+        for (const match of matchAllOutsideCode(linkText, new RegExp(WIKILINK.source, "g"))) {
+            const parsed = parseWikilink(match[1]);
+            const record = parsed.target ? this.resolve(parsed.target) : this.byFile.get(file);
+            if (!record) continue;
+            const start = bodyStart + match.index + (parsed.target ? 2 : 3);
+            found.push({
+                record,
+                anchor: parsed.anchor,
+                location: location(
+                    file,
+                    text,
+                    start,
+                    start + (parsed.target || parsed.anchor).length,
+                ),
+            });
+        }
+        for (const embed of embedsIn(linkText)) {
+            const record = this.resolve(embed.written, { type: EMBED_DEFAULT_TYPE });
+            if (!record) continue;
+            const start = bodyStart + embed.index + 3;
+            found.push({
+                record,
+                anchor: "",
+                location: location(file, text, start, start + embed.written.length),
+            });
+        }
+        if (!bodyStart) return found;
+        const yamlStart = text.indexOf("\n") + 1;
+        const yamlText = text.slice(yamlStart, bodyStart).replace(/\r?\n---(?:\r?\n)?$/, "");
+        let document;
+        try {
+            document = YAML.parseDocument(yamlText);
+        } catch {
+            return found;
+        }
+        if (document.errors.length) return found;
+        const frontmatter = document.toJS();
+        if (!frontmatter || typeof frontmatter !== "object") return found;
+        const visit = (node, segments, position) => {
+            if (!node) return;
+            if (segments.length) {
+                const [head, ...tail] = segments;
+                if (YAML.isMap(node)) {
+                    for (const pair of node.items) {
+                        if (head === "*" || String(pair.key?.value) === String(head))
+                            visit(pair.value, tail, position);
+                    }
+                } else if (YAML.isSeq(node)) {
+                    node.items.forEach((child, index) => {
+                        if (head === "*" || String(index) === String(head))
+                            visit(child, tail, position);
+                    });
+                }
+                return;
+            }
+            const scalar = (part, value) => {
+                if (!YAML.isScalar(part) || typeof value !== "string" || !part.range) return;
+                const record = this.resolve(value, {
+                    system: position.system ?? "none",
+                    type: position.type,
+                });
+                if (!record) return;
+                const start = yamlStart + part.range[0];
+                found.push({
+                    record,
+                    anchor: "",
+                    location: location(file, text, start, yamlStart + part.range[1]),
+                });
+            };
+            if (position.shape === "keys" && YAML.isMap(node)) {
+                for (const pair of node.items) scalar(pair.key, pair.key?.value);
+            } else if (position.shape === "list" && YAML.isSeq(node)) {
+                for (const child of node.items) scalar(child, child?.value);
+            } else if (position.shape === "scalar-or-map" && YAML.isMap(node)) {
+                for (const pair of node.items) scalar(pair.value, pair.value?.value);
+            } else {
+                scalar(node, node.value);
+            }
+        };
+        for (const position of addressPositions(frontmatter))
+            visit(document.contents, position.path, position);
+        return found;
+    }
+
+    targetAt(uri, position) {
+        const text = this.text(uri);
+        if (text == null) return null;
+        const offset = offsetAt(text, position);
+        if (offset < 0) return null;
+        const file = fileURLToPath(uri);
+        const reference = this.referencesInText(text, file).find(({ location: source }) => {
+            const start = offsetAt(text, source.range.start);
+            const end = offsetAt(text, source.range.end);
+            return start <= offset && offset <= end;
+        });
+        if (reference) return { record: reference.record, anchor: reference.anchor };
+        const own = this.byFile.get(file);
+        if (own && /^shortcode:\s*/.test(text.split("\n")[position.line] ?? ""))
+            return { record: own, anchor: "" };
+        const start = text.slice(0, offset).search(/[A-Za-z0-9./]+$/);
+        if (start < 0) return null;
+        const end = offset + (text.slice(offset).match(/^[A-Za-z0-9./]+/)?.[0].length ?? 0);
+        const record = this.resolve(text.slice(start, end));
+        return record ? { record, anchor: "" } : null;
+    }
+
+    definition(uri, position) {
+        this.requireIndex();
+        const target = this.targetAt(uri, position);
+        if (!target) return null;
+        const { record, anchor } = target;
+        const file = this.fileFor(record);
+        if (!file) return null;
+        if (record.asset) return { uri: pathToFileURL(file).href, range: EMPTY_RANGE };
+        const line =
+            anchor ?
+                record.anchors?.find((entry) => entry.slug.toLowerCase() === anchor.toLowerCase())
+                    ?.line
+            :   null;
+        if (anchor && !line) return null;
+        const targetText = fs.readFileSync(file, "utf8");
+        const offset = line ? offsetAt(targetText, { line: line - 1, character: 0 }) : 0;
+        return location(file, targetText, offset, offset);
+    }
+
+    symbols(query) {
+        this.requireIndex();
+        const tag = /^tag:(.*)$/i.exec(query);
+        const needle = (tag ? tag[1] : query).trim().toLowerCase();
+        const found = new Map();
+        for (const record of this.records) {
+            if (!record.file?.path) continue;
+            const values =
+                tag ?
+                    (record.tags ?? [])
+                :   [
+                        record.name?.full,
+                        record.nameAscii,
+                        ...(record.name?.aliases ?? []),
+                        ...(record.aliasesAscii ?? []),
+                        record.shortcode,
+                        record.address?.slug,
+                        record.address?.canonical,
+                    ];
+            const match = values.find(
+                (value) => typeof value === "string" && value.toLowerCase().includes(needle),
+            );
+            if (!match) continue;
+            const file = noteFile(this.contentRoot, record);
+            if (found.has(file)) continue;
+            found.set(file, {
+                name: String(noteName(record)),
+                kind: 1,
+                containerName: `${record.address?.slug ?? [record.type, record.shortcode].filter(Boolean).join(" ")} · ${tag ? `tag: ${match}` : match}`,
+                location: { uri: pathToFileURL(file).href, range: EMPTY_RANGE },
+            });
+        }
+        return [...found.values()];
+    }
+
+    references(uri, position) {
+        this.requireIndex();
+        const target = this.targetAt(uri, position)?.record;
+        if (!target?.address?.canonical) return [];
+        const locations = [];
+        const needle = target.shortcode.toLowerCase();
+        const visit = (directory) => {
+            for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+                if (entry.name.startsWith(".")) continue;
+                const file = path.join(directory, entry.name);
+                if (entry.isDirectory()) {
+                    visit(file);
+                } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+                    const savedText = fs.readFileSync(file, "utf8");
+                    if (!savedText.toLowerCase().includes(needle)) continue;
+                    const text = this.documents.get(pathToFileURL(file).href) ?? savedText;
+                    for (const reference of this.referencesInText(text, file)) {
+                        if (reference.record.address?.canonical === target.address.canonical)
+                            locations.push(reference.location);
+                    }
+                }
+            }
+        };
+        visit(this.contentRoot);
+        return locations;
+    }
+}
+
+/** Process one JSON-RPC request without writing protocol bytes. */
+export function respond(workspace, message) {
+    const { method, params = {} } = message;
+    switch (method) {
+        case "initialize":
+            return {
+                capabilities: {
+                    positionEncoding: "utf-16",
+                    textDocumentSync: 2,
+                    definitionProvider: true,
+                    referencesProvider: true,
+                    workspaceSymbolProvider: true,
+                },
+                serverInfo: { name: "heroiclands-content" },
+            };
+        case "shutdown":
+            return null;
+        case "textDocument/didOpen":
+            workspace.documents.set(params.textDocument.uri, params.textDocument.text);
+            return undefined;
+        case "textDocument/didChange": {
+            const uri = params.textDocument.uri;
+            let text = workspace.text(uri) ?? "";
+            for (const change of params.contentChanges ?? []) {
+                if (!change.range) text = change.text;
+                else {
+                    const start = offsetAt(text, change.range.start);
+                    const end = offsetAt(text, change.range.end);
+                    text = text.slice(0, start) + change.text + text.slice(end);
+                }
+            }
+            workspace.documents.set(uri, text);
+            return undefined;
+        }
+        case "textDocument/didClose":
+            workspace.documents.delete(params.textDocument.uri);
+            return undefined;
+        case "textDocument/definition":
+            return workspace.definition(params.textDocument.uri, params.position);
+        case "textDocument/references":
+            return workspace.references(params.textDocument.uri, params.position);
+        case "workspace/symbol":
+            return workspace.symbols(params.query ?? "");
+        default:
+            return undefined;
+    }
+}
+
+/** Run the stdio language server. */
+export function runLanguageServer(
+    input = process.stdin,
+    output = process.stdout,
+    workspace = new ContentWorkspace(),
+) {
+    let pending = Buffer.alloc(0);
+    const send = (message) => {
+        const body = Buffer.from(JSON.stringify(message));
+        output.write(`Content-Length: ${body.length}\r\n\r\n`);
+        output.write(body);
+    };
+    input.on("data", (chunk) => {
+        pending = Buffer.concat([pending, chunk]);
+        while (true) {
+            const separator = pending.indexOf("\r\n\r\n");
+            if (separator < 0) break;
+            const header = pending.subarray(0, separator).toString("ascii");
+            const length = /^content-length:\s*(\d+)\s*$/im.exec(header)?.[1];
+            if (!length) throw new Error("LSP message has no Content-Length");
+            const end = separator + 4 + Number(length);
+            if (pending.length < end) break;
+            const body = pending.subarray(separator + 4, end);
+            pending = pending.subarray(end);
+            let message;
+            try {
+                message = JSON.parse(body.toString("utf8"));
+            } catch (error) {
+                send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: String(error) } });
+                continue;
+            }
+            if (message.method === "exit") {
+                process.exitCode = 0;
+                input.pause();
+                return;
+            }
+            try {
+                const result = respond(workspace, message);
+                if (message.id !== undefined)
+                    send(
+                        result === undefined ?
+                            {
+                                jsonrpc: "2.0",
+                                id: message.id,
+                                error: { code: -32601, message: "Method not found" },
+                            }
+                        :   { jsonrpc: "2.0", id: message.id, result },
+                    );
+            } catch (error) {
+                if (message.id !== undefined)
+                    send({
+                        jsonrpc: "2.0",
+                        id: message.id,
+                        error: { code: -32603, message: String(error) },
+                    });
+            }
+        }
+    });
+}

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.3",
     "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",
@@ -96,7 +96,8 @@
     },
     "bin": {
         "package-build": "./bin/package-build.mjs",
-        "content-build": "./bin/content-build.mjs"
+        "content-build": "./bin/content-build.mjs",
+        "heroiclands-content-language-server": "./bin/heroiclands-content-language-server.mjs"
     },
     "files": [
         "CHANGELOG-content-build.md",

package/types/engine/content-language-server.d.mts

@@ -0,0 +1,64 @@
+/** Process one JSON-RPC request without writing protocol bytes. */
+export function respond(workspace: any, message: any): any;
+/** Run the stdio language server. */
+export function runLanguageServer(input?: NodeJS.ReadStream & {
+    fd: 0;
+}, output?: NodeJS.WriteStream & {
+    fd: 1;
+}, workspace?: ContentWorkspace): void;
+/** An index read from the package's configured content tree. */
+export class ContentWorkspace {
+    constructor(config?: import("../content-config.mjs").ContentBuildConfig);
+    config: import("../content-config.mjs").ContentBuildConfig;
+    contentRoot: string;
+    indexFile: string;
+    indexState: string;
+    records: any[];
+    byAddress: Map<any, any>;
+    byFile: Map<any, any>;
+    types: Set<string>;
+    documents: Map<any, any>;
+    refresh(): boolean;
+    requireIndex(): void;
+    fileFor(record: any): string | null;
+    text(uri: any): any;
+    /** Resolve a written Address using the same tuple grammar as the build. */
+    resolve(value: any, defaults?: {}): any;
+    /** Link and declared frontmatter targets, with exact source ranges. */
+    referencesInText(text: any, file: any): {
+        record: any;
+        anchor: string;
+        location: {
+            uri: string;
+            range: {
+                start: {
+                    line: number;
+                    character: number;
+                };
+                end: {
+                    line: number;
+                    character: number;
+                };
+            };
+        };
+    }[];
+    targetAt(uri: any, position: any): {
+        record: any;
+        anchor: string;
+    } | null;
+    definition(uri: any, position: any): {
+        uri: string;
+        range: {
+            start: {
+                line: number;
+                character: number;
+            };
+            end: {
+                line: number;
+                character: number;
+            };
+        };
+    } | null;
+    symbols(query: any): any[];
+    references(uri: any, position: any): any[];
+}

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