@heroiclands/package-build 23.7.1 → 23.8.0

package/docs/reference/format-details.md

@@ -764,6 +764,38 @@ declares the key. Any other art key authored where no pass emits it, such as a
 the note still compiles correctly and a site template may read there what no
 document carries. `null` is never reported.
 
+#### Deliberate cross-references
+
+Every note type accepts `data.seeAlso`: an ordered list of maps with a required
+`address` and an optional string `gloss`. The Address names a whole note,
+defaults to the current package and the `note` system, and has no default type.
+It may name a note in a declared dependency. A gloss is a short plain-text
+phrase explaining the connection.
+
+```yaml
+data:
+  seeAlso:
+    - address: lore-harborhistory
+      gloss: The founding of the port
+    - address: place-breakwater
+    - address: thalorna-note-lore-searoutes
+      gloss: Routes beyond the bay
+```
+
+The vocabulary declares the closed entry shape. The note boundary decodes each
+nested Address, and the frontmatter check locates unresolved, duplicate and
+self references at `data.seeAlso.<index>.address`. Duplicate detection compares
+resolved destinations, so alternative spellings of one target do not make two
+entries. Anchors are not accepted.
+
+On the website, `related.seeAlso` carries `{ title, url, type, gloss? }` entries
+in authored order. The theme renders that group ahead of the inferred
+backlinks and mentions, with duplicates removed by resolved URL. Deliberate
+references can point outside the local site to declared dependency pages.
+The field has no infobox row. Foundry journals append a See also page with
+compendium links; books append a See also section with the book renderer's
+normal internal or external links. An absent or empty list emits nothing.
+
 #### The art slots
 
 A note declares the art its document needs, and every other image in it is
@@ -821,15 +853,18 @@ are, so a key legal everywhere is stated once here rather than repeated in
 twenty-five tables where the one that was mistyped would be the one nobody
 noticed:
 
-| shared `data` property | Values                | Description                                                  |
-| ---------------------- | --------------------- | ------------------------------------------------------------ |
-| `id`                   | `string`              | A pinned document identity.                                  |
-| `pack`                 | `string`              | The shared compendium route.                                 |
-| `packFolder`           | `Address` or pack map | The shared compendium folder Address.                        |
-| `harnworld`            | `{ realm?, ritual? }` | HârnWorld source details.                                    |
-| `harnworld.realm`      | `string`              | The HârnWorld realm the subject belongs to.                  |
-| `harnworld.ritual`     | `string[]`            | The HârnWorld religions the subject observes.                |
-| `banner`               | `Address`             | The page's hero image — an `image` address, cut to 1792×768. |
+| shared `data` property | Values                        | Description                                                                                |
+| ---------------------- | ----------------------------- | ------------------------------------------------------------------------------------------ |
+| `seeAlso`              | list of `{ address, gloss? }` | Deliberate cross-references in reading order, shown on the site, in journals and in books. |
+| `seeAlso[].address`    | a note `Address`              | Required; the whole note to read next.                                                     |
+| `seeAlso[].gloss`      | `string`                      | An optional short phrase saying why to follow the reference.                               |
+| `id`                   | `string`                      | A pinned document identity.                                                                |
+| `pack`                 | `string`                      | The shared compendium route.                                                               |
+| `packFolder`           | `Address` or pack map         | The shared compendium folder Address.                                                      |
+| `harnworld`            | `{ realm?, ritual? }`         | HârnWorld source details.                                                                  |
+| `harnworld.realm`      | `string`                      | The HârnWorld realm the subject belongs to.                                                |
+| `harnworld.ritual`     | `string[]`                    | The HârnWorld religions the subject observes.                                              |
+| `banner`               | `Address`                     | The page's hero image — an `image` address, cut to 1792×768.                               |
 
 `data.harnworld` takes two keys and nothing else: `realm`, a string naming the
 HârnWorld realm the subject belongs to, and `ritual`, a list of strings naming

package/docs/reference/note-types.md

@@ -34,6 +34,7 @@ These fields are accepted by every note type. A field's value can still be irrel
 
 | Field             | Shape                                           | Meaning                                                                                                                       |
 | ----------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `data.seeAlso`    | list of `{ address, gloss? }`                   | Deliberate cross-references in reading order, with optional glosses; shown on the site, in journals and in books.             |
 | `data.id`         | string                                          | A fixed document identity when the derived identity is unsuitable.                                                            |
 | `data.pack`       | string                                          | The shared compendium route, with a system block overriding it.                                                               |
 | `data.packFolder` | an Address, or a map of Addresses keyed by pack | The shared compendium folder Address, with a system block overriding it.                                                      |
@@ -42,10 +43,12 @@ These fields are accepted by every note type. A field's value can still be irrel
 
 **Inner keys** — a key a field's value does not declare is an error at its own line and column.
 
-| Key                     | Shape           | Required | Meaning                                       |
-| ----------------------- | --------------- | -------- | --------------------------------------------- |
-| `data.harnworld.realm`  | a string        | no       | The HârnWorld realm the subject belongs to.   |
-| `data.harnworld.ritual` | list of strings | no       | The HârnWorld religions the subject observes. |
+| Key                      | Shape           | Required | Meaning                                            |
+| ------------------------ | --------------- | -------- | -------------------------------------------------- |
+| `data.seeAlso[].address` | a note Address  | yes      | The note to read next.                             |
+| `data.seeAlso[].gloss`   | a string        | no       | A short phrase saying why to follow the reference. |
+| `data.harnworld.realm`   | a string        | no       | The HârnWorld realm the subject belongs to.        |
+| `data.harnworld.ritual`  | list of strings | no       | The HârnWorld religions the subject observes.      |
 
 ## Type-specific fields
 

package/e2e.mjs

@@ -43,6 +43,8 @@ import crypto from "node:crypto";
 import { readdirSync, statSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import os from "node:os";
+import { Browser, BrowserPlatform, computeExecutablePath, install } from "@puppeteer/browsers";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
 
@@ -796,6 +798,91 @@ export function suiteExecutables(command) {
     return [program];
 }
 
+/** The Chrome for Testing build shared by local and CI Cypress runs. */
+export const CHROME_BUILD_ID = "155.0.8059.84";
+
+/**
+ * The browser cache survives reseeding and container teardown.
+ * @param {NodeJS.ProcessEnv} [env] - Environment overrides.
+ * @returns {string} The browser cache directory.
+ */
+export function browserCacheDir(env = process.env) {
+    if (env.HL_BROWSER_CACHE) return path.resolve(env.HL_BROWSER_CACHE);
+    if (env.FOUNDRYVTT_CACHE) return path.resolve(env.FOUNDRYVTT_CACHE, "..", "browser-cache");
+    if (env.HL_E2E_ROOT) return path.resolve(env.HL_E2E_ROOT, "browser-cache");
+    const cache =
+        env.XDG_CACHE_HOME ||
+        (process.platform === "darwin" ?
+            path.join(os.homedir(), "Library", "Caches")
+        :   path.join(os.homedir(), ".cache"));
+    return path.join(cache, "heroiclands", "chrome-for-testing");
+}
+
+/**
+ * Supply pinned Chrome only to a recognizable Cypress command without a browser.
+ * Explicit browser arguments remain verbatim, including Electron and paths.
+ * @param {object} opts
+ * @param {readonly string[]} opts.command - The configured suite command.
+ * @param {string[]} [opts.args] - Extra suite arguments.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Cache overrides.
+ * @param {string} [opts.platform] - Host operating system.
+ * @param {string} [opts.arch] - Host architecture.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<string[]>} Arguments to append to the suite command.
+ */
+export async function prepareSuiteBrowser({
+    command,
+    args = [],
+    env = process.env,
+    platform = process.platform,
+    arch = process.arch,
+    log = () => {},
+}) {
+    const tool = suiteExecutables(command).at(-1);
+    if (!tool || executableName(tool) !== "cypress") return args;
+    const all = [...command, ...args];
+    const explicit = all.findLastIndex(
+        (arg) => arg === "--browser" || arg.startsWith("--browser="),
+    );
+    if (explicit !== -1) {
+        const selected =
+            all[explicit] === "--browser" ?
+                all[explicit + 1]
+            :   all[explicit].slice("--browser=".length);
+        log(
+            `▸ Cypress browser: ${selected ?? "(missing --browser value)"} (explicit; version reported by Cypress)`,
+        );
+        return args;
+    }
+    const browserPlatform =
+        platform === "darwin" && arch === "arm64" ? BrowserPlatform.MAC_ARM
+        : platform === "linux" && arch === "x64" ? BrowserPlatform.LINUX
+        : null;
+    if (!browserPlatform)
+        throw new Error(
+            `Chrome for Testing has no configured build for ${platform}/${arch}. Pass --browser <name-or-path> to select an installed browser.`,
+        );
+    const options = {
+        browser: Browser.CHROME,
+        buildId: CHROME_BUILD_ID,
+        platform: browserPlatform,
+        cacheDir: browserCacheDir(env),
+    };
+    let executablePath = computeExecutablePath(options);
+    if (!isExecutableFile(executablePath)) {
+        try {
+            executablePath = (await install(options)).executablePath;
+        } catch (cause) {
+            throw new Error(
+                `Cannot install Chrome for Testing ${CHROME_BUILD_ID} for ${platform}/${arch} in ${options.cacheDir}. Check network access or pass --browser <name-or-path>.`,
+                { cause },
+            );
+        }
+    }
+    log(`▸ Cypress browser: Chrome for Testing ${CHROME_BUILD_ID} (${executablePath})`);
+    return [...args, "--browser", executablePath];
+}
+
 /**
  * @param {string} candidate - An absolute path.
  * @returns {boolean} Whether it is there and is a file.
@@ -1128,7 +1215,7 @@ export async function e2eRun({
         });
         return runSuite({
             command,
-            args: suiteArgs,
+            args: await prepareSuiteBrowser({ command, args: suiteArgs, env, log }),
             cwd: config.rootDir,
             // Only a headless run makes a claim worth checking. `open` hands
             // the runner to a person, who decides what to execute and when to
@@ -1211,7 +1298,7 @@ export async function e2eFast({ config, argv = [], env = process.env, log = () =
     }
     return runSuite({
         command,
-        args: suiteArgs,
+        args: await prepareSuiteBrowser({ command, args: suiteArgs, env, log }),
         cwd: config.rootDir,
         results: config.e2eResults,
         env,

package/engine/base-compiler.mjs

@@ -1254,19 +1254,18 @@ export class BasePackCompiler {
             }
         }
 
-        // The corpus, from the index this compile derived once — not a walk of
-        // this pass's own. Each note is then read for its **prose**: the
-        // index carries what is *about* a note and deliberately not its text,
-        // nor the `bodyLine`/`bodyColumn` a diagnostic needs, and this pass has
-        // to have the body anyway. So the read is one this pass makes anyway;
-        // the index decides which files it covers.
+        // Parsed source and body coordinates belong to the shared corpus.
+        // A directly supplied corpus can fill missing entries on first use.
+        this.corpus.parsed ??= new Map();
         const dates = reckoningContext({ notes: this.corpus.records });
         /** The note first filed under each document id in this pass. @type {Map<string, string>} */
         const idOwners = new Map();
         for (const record of this.corpus.records) {
             if (!isNoteRecord(record)) continue;
             const absPath = noteFile(this.contentBase, record);
-            const { body, bodyLine, bodyColumn } = parseMarkdownFile(absPath);
+            const parsed = this.corpus.parsed.get(absPath) ?? parseMarkdownFile(absPath);
+            this.corpus.parsed.set(absPath, parsed);
+            const { body, bodyLine, bodyColumn, raw } = parsed;
             const fm = cloneAddressState(authoredFrontmatter(record));
             // Which note this pass is on, so anything it calls can report a
             // position without every method having to be handed one.
@@ -1284,7 +1283,7 @@ export class BasePackCompiler {
             // comes from the diagnostic locator, so the message must not
             // repeat it.
             try {
-                assertNoDeclaredPackage(fm, { absPath });
+                assertNoDeclaredPackage(fm, { absPath, raw });
             } catch (err) {
                 stats.declined++;
                 this.errorCount++;
@@ -1375,7 +1374,7 @@ export class BasePackCompiler {
                         `${path.relative(process.cwd(), owner)}. Give one of the two notes a ` +
                         `different \`id\` under \`data:\`, or remove it to take the id derived ` +
                         `from its address`,
-                    locateFrontmatterKey(absPath, "id"),
+                    locateFrontmatterKey(absPath, "id", undefined, { raw }),
                 );
                 continue;
             }
@@ -1398,15 +1397,9 @@ export class BasePackCompiler {
                 );
                 const position =
                     err.position ??
-                    (err.keyPath ?
-                        positionOfFrontmatterPath(fs.readFileSync(absPath, "utf8"), err.keyPath)
-                    : repeatedAnchor ?
-                        positionOfLiteral(
-                            fs.readFileSync(absPath, "utf8"),
-                            `{#${repeatedAnchor[1]}}`,
-                            2,
-                        )
-                    :   undefined);
+                    (err.keyPath ? positionOfFrontmatterPath(raw, err.keyPath)
+                    : repeatedAnchor ? positionOfLiteral(raw, `{#${repeatedAnchor[1]}}`, 2)
+                    : undefined);
                 // `position` is set by whatever failed if it knew where — an
                 // unresolved address, a bad table directive — so the report
                 // points at the line rather than at the note.

package/engine/compile-corpus.mjs

@@ -60,7 +60,7 @@ import { prepareTreeSqlTables } from "./sql-tables.mjs";
  *   created when none is passed, and returned on the corpus either way — a note
  *   the index refuses is a note the compile must still *report*, exactly as the
  *   compile loop reported it when the loop was the first to see it.
- * @returns {Promise<{records: object[], linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
+ * @returns {Promise<{records: object[], parsed: Map<string, object>, linkIndex: object, sqlTables: Map<string, object[]>|undefined, problems: object[]}>} The corpus,
  *   its indexes, and the notes it could not record.
  */
 export async function buildCompileCorpus({
@@ -86,6 +86,7 @@ export async function buildCompileCorpus({
     const sqlOptions = { ...corpusOptions, skipDirectories, parsed };
     return {
         records,
+        parsed,
         problems: collected,
         linkIndex: buildContentLinkIndex(contentBase, router, corpusOptions),
         sqlTables: await prepareTreeSqlTables(contentBase, sqlOptions),

package/engine/content-alerts.mjs

@@ -48,7 +48,7 @@ export const ALERT_TYPES = Object.freeze({
         ),
     },
 });
-const parser = new MarkdownIt();
+const parser = new MarkdownIt({ html: true });
 const titleParser = new MarkdownIt({ html: false });
 const marker = /^ {0,3}>[ \t]?\[!([^\]\n]+)\](.*)$/;
 /** Read alerts outside code examples, retaining inclusive source line ranges.
@@ -85,7 +85,9 @@ export function scanAlerts(source) {
         if (match[1] !== match[1].toUpperCase() || !Object.hasOwn(ALERT_TYPES, type)) {
             errors.push({
                 ...at,
-                message: `unknown alert type ${match[1]}; use NOTE, TIP, IMPORTANT or WARNING`,
+                message: `unknown alert type ${match[1]}; use ${Object.keys(ALERT_TYPES)
+                    .map((name) => name.toUpperCase())
+                    .join(", ")}`,
             });
             continue;
         }

package/engine/content-blocks.mjs

@@ -62,6 +62,7 @@ import { WITHHELD_CLASS, parseHeadingLine, withheldSections } from "./heading-at
  * and a stray `<section>` would close the block early.
  */
 const titleParser = new MarkdownIt({ html: false });
+const structureParser = new MarkdownIt({ html: true });
 
 /** The blocks an author may open, with the heading each takes by default. */
 export const BLOCK_NAMES = Object.freeze({
@@ -99,28 +100,24 @@ function escapeAttribute(value) {
  * @returns {{blocks: Array<{name: string, title: string, id: string, classes: string[], attributes: Record<string, string>, start: number, end: number, body: string}>, errors: Array<{line: number, column: number, message: string}>}}
  */
 export function scanBlocks(source) {
-    const lines = String(source ?? "").split("\n"),
+    const lines = String(source ?? "").split(/\r?\n/),
         blocks = [],
         errors = [];
     const stack = [];
-    let fence = null;
+    // A bare fence can belong to a quote through lazy continuation.
+    // Parser ranges decide whether it can delimit a container.
+    const literalLines = new Set();
+    for (const token of structureParser.parse(String(source ?? ""), {})) {
+        if (
+            !token.map ||
+            !["blockquote_open", "fence", "code_block", "html_block"].includes(token.type)
+        )
+            continue;
+        for (let line = token.map[0]; line < token.map[1]; line++) literalLines.add(line);
+    }
     for (let i = 0; i < lines.length; i++) {
+        if (literalLines.has(i)) continue;
         const line = lines[i];
-        const code = /^ *(`{3,}|~{3,})(.*)$/.exec(line);
-        if (fence) {
-            if (
-                code &&
-                code[1][0] === fence[0] &&
-                code[1].length >= fence.length &&
-                !code[2].trim()
-            )
-                fence = null;
-            continue;
-        }
-        if (code) {
-            fence = code[1];
-            continue;
-        }
         const close = /^ *:::\s*$/.test(line);
         const named = /^ *:::([A-Za-z][A-Za-z0-9-]*)(?:\s+(.*))?$/.exec(line);
         const div = /^ *:::\s+(\{.*)$/.exec(line);
@@ -135,7 +132,7 @@ export function scanBlocks(source) {
             if (!block.body)
                 errors.push({
                     line: block.start + 1,
-                    column: 1,
+                    column: lines[block.start].indexOf(":::") + 1,
                     message: `${block.name} block is empty`,
                 });
             if (!stack.length) blocks.push(block);
@@ -144,7 +141,7 @@ export function scanBlocks(source) {
         if (!close && !named && !div) continue;
         const name = named?.[1] ?? "div",
             raw = named?.[2] ?? div?.[1] ?? "";
-        const at = { line: i + 1, column: 1 };
+        const at = { line: i + 1, column: line.indexOf(":::") + 1 };
         if (name !== "div" && !Object.hasOwn(BLOCK_NAMES, name)) {
             errors.push({ ...at, message: `there is no ${name} block; the blocks are ${names()}` });
             stack.push({ start: i, rejected: true });
@@ -189,27 +186,12 @@ export function scanBlocks(source) {
         if (!block.rejected)
             errors.push({
                 line: block.start + 1,
-                column: 1,
+                column: lines[block.start].indexOf(":::") + 1,
                 message: `${block.name} block needs a closing ::: line`,
             });
     for (const block of blocks) {
-        let literal = null;
         for (let i = block.start + 1; i < block.end; i++) {
-            const marker = /^ *(`{3,}|~{3,})(.*)$/.exec(lines[i]);
-            if (literal) {
-                if (
-                    marker &&
-                    marker[1][0] === literal[0] &&
-                    marker[1].length >= literal.length &&
-                    !marker[2].trim()
-                )
-                    literal = null;
-                continue;
-            }
-            if (marker) {
-                literal = marker[1];
-                continue;
-            }
+            if (literalLines.has(i)) continue;
             if (parseHeadingLine(lines[i])?.startsPage)
                 errors.push({
                     line: i + 1,

package/engine/content-index.mjs

@@ -410,23 +410,25 @@ function foundryBlock(entry, system) {
  * @param {string} [absPath] - The file, read only on the failing path to locate
  *   the offending key.
  * @param {string} [contentPackage] - The package this tree compiles as.
+ * @param {string} [raw] - Source text already read by the caller.
  * @returns {void}
  * @throws {Error} When the note authors a derived key. `file` and `position`
  *   ride on the error.
  */
-function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
+function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage, raw) {
     for (const key of DERIVED_KEYS) {
         if (!Object.hasOwn(frontmatter ?? {}, key)) continue;
         if (key === "package") {
             // Throws with its own wording, and its own position.
-            assertNoDeclaredPackage(frontmatter, { absPath, configured: contentPackage });
+            assertNoDeclaredPackage(frontmatter, { absPath, configured: contentPackage, raw });
         }
         const err = new Error(
             `\`${key}:\` is derived by the content index and cannot be ` +
                 `authored — rename the frontmatter field`,
         );
         err.file = relPath;
-        const position = absPath ? locateFrontmatterKey(absPath, key) : undefined;
+        const position =
+            absPath ? locateFrontmatterKey(absPath, key, undefined, { raw }) : undefined;
         if (position) err.position = position;
         throw err;
     }
@@ -445,6 +447,7 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
  * @param {string} options.relPath - Its path below the content root, POSIX-separated.
  * @param {string} [options.absPath] - The file, read only on the failing path to
  *   locate the offending key.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @param {string} options.contentPackage - The package the tree compiles as.
  * @param {string} [options.body] - The note's markdown body, for its anchors
  *   and for the one question that decides whether the note publishes a page. A
@@ -473,6 +476,7 @@ export function buildIndexRecord({
     frontmatter,
     relPath,
     absPath,
+    raw,
     contentPackage,
     body,
     bodyLine,
@@ -481,7 +485,7 @@ export function buildIndexRecord({
     dateContext,
     resolveRole,
 }) {
-    assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage);
+    assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage, raw);
 
     const posix = relPath.split(path.sep).join("/");
     const folder = posix.includes("/") ? posix.slice(0, posix.lastIndexOf("/")) : "";
@@ -490,9 +494,7 @@ export function buildIndexRecord({
     } catch (error) {
         error.file = absPath ?? relPath;
         if (absPath && error.keyPath) {
-            const yamlText = fs
-                .readFileSync(absPath, "utf8")
-                .match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+            const yamlText = (raw ?? rawNote(absPath)).match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
             const locate = (/** @type {any} */ found) => {
                 const position = positionOfYamlPath(yamlText, found.keyPath, {
                     key: found.addressKey,
@@ -540,7 +542,7 @@ export function buildIndexRecord({
                     stub ? null : (
                         [
                             ...collectAnchors(body, bodyLine, resolveRole),
-                            ...eventAnchors(frontmatter, rawNote(absPath)),
+                            ...eventAnchors(frontmatter, raw ?? rawNote(absPath)),
                         ]
                             .sort((a, b) => (a.line ?? 0) - (b.line ?? 0))
                             .map((a) => ({
@@ -659,6 +661,7 @@ export function indexRecordsForNote({
     bodyLine,
     relPath,
     absPath,
+    raw,
     contentPackage,
     manifest,
     addressContext,
@@ -672,6 +675,7 @@ export function indexRecordsForNote({
         bodyLine,
         relPath,
         absPath,
+        raw,
         contentPackage,
         manifest,
         addressContext,
@@ -783,10 +787,14 @@ function cultureTuple(value) {
  *   immediate parent whose package is not this one.
  * @param {object[]} [options.problems] - Receives each conflict as a finding.
  *   Omitted, every conflict is collected and one Error lists them all.
+ * @param {Map<string, {raw: string}>} [options.parsed] - Notes already read, keyed by file.
  * @returns {Array<Record<string, any>>} The same records.
  * @throws {Error} When `problems` is omitted and any note's sources disagree.
  */
-export function resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems }) {
+export function resolveCultures(
+    records,
+    { contentPackage, contentBase, foreignRecord, problems, parsed },
+) {
     // Each note under every key a link may name it by: its record's canonical
     // address, and its page address in the `note` system, which is what a
     // `data.parents`, `data.seat` or `data.government` link names.
@@ -879,7 +887,7 @@ export function resolveCultures(records, { contentPackage, contentBase, foreignR
      */
     const conflict = (record, keyPath, subject, distinct) => {
         const file = contentBase ? noteFile(contentBase, record) : record.file?.path;
-        const raw = contentBase && fs.existsSync(file) ? fs.readFileSync(file, "utf8") : undefined;
+        const raw = parsed?.get(file)?.raw ?? (contentBase ? rawNote(file) : undefined);
         let position = positionOfFrontmatterPath(raw, keyPath, { key: true });
         if (position.line === undefined && keyPath.length > 1)
             position = positionOfFrontmatterPath(raw, ["data"], { key: true });
@@ -1026,9 +1034,9 @@ export function resolveCultures(records, { contentPackage, contentBase, foreignR
  * @param {(key: string) => ({culture?: unknown}|undefined)} [options.foreignRecord] -
  *   Another package's entry for a canonical address, read for a parent that
  *   package publishes; see {@link resolveCultures}.
- * @param {Map<string, {body: string, frontmatter: object|null}>} [options.parsed] -
- *   Filled with each note's body and its frontmatter as authored, keyed by the
- *   note's file, so a later pass reads the notes this walk already parsed.
+ * @param {Map<string, {body: string, frontmatter: object|null, raw: string, bodyLine?: number, bodyColumn?: number}>} [options.parsed] -
+ *   Filled with each note's source text, body coordinates and frontmatter as
+ *   authored, keyed by file, for reuse throughout the command.
  * @returns {Array<Record<string, any>>} The records, in a total order that does
  *   not depend on directory-read order.
  */
@@ -1042,7 +1050,7 @@ export function collectContentIndex(
         problems,
         addressContext,
         foreignRecord,
-        parsed,
+        parsed = new Map(),
     },
 ) {
     const records = [];
@@ -1115,10 +1123,16 @@ export function collectContentIndex(
 
     // Each recorded note with its body, for the words its prose cites.
     const bodies = [];
-    for (const { frontmatter, body, bodyLine, absPath } of parsedNotes) {
+    for (const { frontmatter, body, bodyLine, bodyColumn, raw, absPath } of parsedNotes) {
         // Before the index derives anything onto the frontmatter, so a later
         // pass reads the note as authored.
-        parsed?.set(absPath, { body, frontmatter: structuredClone(frontmatter) });
+        parsed.set(absPath, {
+            body,
+            bodyLine,
+            bodyColumn,
+            raw,
+            frontmatter: structuredClone(frontmatter),
+        });
         const fm = frontmatter ?? {};
         applyComputedBeingAge(fm, present, dates);
         const relPath = path.relative(contentBase, absPath);
@@ -1127,6 +1141,7 @@ export function collectContentIndex(
                 frontmatter: fm,
                 relPath,
                 absPath,
+                raw,
                 contentPackage,
                 body,
                 bodyLine,
@@ -1142,9 +1157,7 @@ export function collectContentIndex(
                 err.identity = { type: fm.type, shortcode: fm.shortcode };
                 err.keyPath = ["shortcode"];
                 err.message = `shortcode "${fm.shortcode}" is not strictly alphanumeric — lowercase letters and digits only`;
-                const yamlText = fs
-                    .readFileSync(absPath, "utf8")
-                    .match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+                const yamlText = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
                 err.position = positionOfYamlPath(yamlText, err.keyPath);
                 if (err.position.line) err.position.line++;
             }
@@ -1186,13 +1199,13 @@ export function collectContentIndex(
     // Every note record exists and every Address in it is a tuple, so a parent
     // is found by its canonical address. Before the sort, which reads nothing
     // the pass writes.
-    resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems });
+    resolveCultures(records, { contentPackage, contentBase, foreignRecord, problems, parsed });
     const cultureNotes = records
         .filter((record) => isNoteRecord(record) && record.type === "lore")
         .map((record) => ({
             fm: record,
             file: noteFile(contentBase, record),
-            raw: fs.readFileSync(noteFile(contentBase, record), "utf8"),
+            raw: parsed.get(noteFile(contentBase, record)).raw,
         }));
     const cultureByKey = new Map(
         cultureNotes.map((note) => [
@@ -1352,7 +1365,7 @@ function dependencyAddresses(config) {
  *   aborting the derivation. Omitted, the note throws — which is the contract
  *   the emitter needs, since an index missing a note asserts that it does not
  *   exist.
- * @param {Map<string, {body: string, frontmatter: object|null}>} [opts.parsed] -
+ * @param {Map<string, {body: string, frontmatter: object|null, raw: string, bodyLine?: number, bodyColumn?: number}>} [opts.parsed] -
  *   Filled with each note's body and authored frontmatter, keyed by the note's
  *   file. Handed to {@link module:engine/sql-tables.prepareTreeSqlTables}, it
  *   spares that pass reading and parsing every note again.

package/engine/content-poetry.mjs

@@ -71,9 +71,12 @@ export function poetryMarkdown(body) {
         .join("\n\n");
 }
 
+import MarkdownIt from "markdown-it";
 import { slugify } from "./content-slug.mjs";
 import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
 
+const structureParser = new MarkdownIt({ html: true });
+
 /** Read poetry code fences; start/end are inclusive zero-based source lines.
  * @param {string} source - Authored Markdown.
  */
@@ -81,8 +84,14 @@ export function scanPoetry(source) {
     const lines = String(source ?? "").split("\n"),
         blocks = [],
         errors = [];
+    const literalLines = new Set();
+    for (const token of structureParser.parse(String(source ?? ""), {})) {
+        if (!token.map || !["blockquote_open", "html_block"].includes(token.type)) continue;
+        for (let line = token.map[0]; line < token.map[1]; line++) literalLines.add(line);
+    }
     let opening = null;
     for (let i = 0; i < lines.length; i++) {
+        if (literalLines.has(i)) continue;
         const match = /^ *(`{3,}|~{3,})(.*)$/.exec(lines[i]);
         if (opening) {
             if (