@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/note-vocabulary.mjs

@@ -42,24 +42,25 @@
  * transmission — and is true of it whichever system is reading. What each
  * system makes of that value is declared elsewhere, in that system's own half.
  *
- * **The type names here are today's**, which for four of them is not the name
- * the specification uses: `armor`, `weapon`, `projectile` and `concoction` are
- * still spelled `armorgear`, `weapongear`, `projectilegear` and
- * `concoctiongear`, and a `map` is still one of `battlemap` / `localmap` /
- * `regionalmap`. Those renames are a later slice (#78, #79), and declaring the
- * vocabulary under a name no note may yet carry would make it unreachable. The
- * specification's types with no name here at all — `place`, `scenario`,
- * `lore`, `vehicle`, `armorlocation` — are likewise deferred: a note carrying
- * one is already reported as a type no schema declares, which is the finding it
- * deserves until the type exists.
+ * **The type names here are the specification's**, since #78 renamed `armor`,
+ * `projectile` and `concoction` off the `…gear` spellings that named a SoHL
+ * document subtype rather than the thing the note is about. `weapon` is the one
+ * the specification and this registry still spell differently: both systems
+ * call that document a `weapongear`, so the name says nothing system-specific
+ * and #78's table has no row for it. A note left on a renamed spelling still
+ * reaches its entry — every type-keyed lookup normalises through
+ * `RENAMED_TYPES` — and is reported rather than refused until the content trees
+ * have swept.
  *
  * **A type name and a subType value are held to the address charset** (#206), so
  * both are `^[A-Za-z0-9]+$` — the charset `engine/address-charset.mjs` states
- * and the shortcode is already held to. For a type that is literal: it is the
- * first segment of every address (`type-shortcode`), the hyphen is the
- * separator between segments and can therefore never occur inside one, and a
- * hyphenated name would be read back as two segments and resolve to nothing,
- * reporting nothing about why.
+ * and the shortcode is already held to. For a type that is literal: it is a
+ * segment of every address — the first of the short form an author writes
+ * (`type-shortcode`), the third of the canonical
+ * `package-system-type-shortcode` — the hyphen is the separator between
+ * segments and can therefore never occur inside one, and a hyphenated name
+ * would be read back as two segments and resolve to nothing, reporting nothing
+ * about why.
  *
  * A subType reaches no address of its own. It did when this rule was written —
  * a `doc`'s was its section, a path segment — and #204 retired sections from
@@ -77,6 +78,10 @@
 // The one charset, read rather than restated. A second spelling of the pattern
 // is how the three disagreements found in #202/#203 happened.
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
+// The retirement window for a renamed type, read rather than restated: a
+// vocabulary that answered only to the current spelling would report every key
+// of an unswept note as unknown (#78).
+import { currentType } from "./ids.mjs";
 
 /**
  * One `data:` key a note type may carry.
@@ -90,12 +95,19 @@ import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs
  * @typedef {object} DataFieldSpec
  * @property {string} name - The key under `data:`, dotted for a nested one
  *   (`charges.value`).
- * @property {"string"|"number"|"boolean"|"list"|"map"} [kind] - The value's
- *   shape, for the lint. Absent means no claim is made about the value — which
- *   is the honest answer wherever the specification's stated shape and the
- *   shape notes are authored in today disagree.
+ * @property {"string"|"number"|"boolean"|"list"|"map"|"scalar-or-map"} [kind] -
+ *   The value's shape, for the lint. Absent means no claim is made about the
+ *   value — which is the honest answer wherever the specification's stated
+ *   shape and the shape notes are authored in today disagree.
  * @property {string} [shape] - Human-readable shape, for a finding and for
  *   documentation.
+ * @property {string} [entryShape] - For a `scalar-or-map` field, what one
+ *   entry of the map is. A finding names the entry at fault rather than
+ *   quoting the whole map back, so the string an author has to correct is the
+ *   one the message holds.
+ * @property {"pack"} [keys] - For a `scalar-or-map` field, what its keys name.
+ *   `"pack"` means each is a pack this package declares, so a key naming none
+ *   is a finding of its own: it addresses a hierarchy nothing will ever read.
  * @property {string} describe - One line, for the author-facing reference.
  */
 
@@ -136,6 +148,26 @@ const LINK = Object.freeze({ shape: "a wikilink", kind: "string" });
 /** A list of wikilinks. */
 const LINKS = Object.freeze({ shape: "list of wikilinks", kind: "list" });
 
+/**
+ * A single wikilink, or one per pack.
+ *
+ * The map form is not a convenience spelling of the scalar: it says something
+ * the scalar cannot, that the answer *differs by pack*. A folder's `parent` is
+ * the case it exists for — a folder's identity is one thing and its hierarchy
+ * another, and both large trees file the same folder under a different parent
+ * in the items pack and the journals pack (#276).
+ *
+ * Typing it as a bare {@link LINK} is what #288 was: the compiler read both
+ * forms and the lint rejected one of them, so every note using the form the
+ * specification prescribes was a finding and no note using it was not.
+ */
+const LINK_BY_PACK = Object.freeze({
+    shape: "a wikilink, or a map of wikilinks keyed by pack",
+    kind: "scalar-or-map",
+    entryShape: "a wikilink",
+    keys: "pack",
+});
+
 /** Whatever the author wrote — declared, but with no claim about its shape. */
 const ANY = Object.freeze({ shape: "as authored" });
 
@@ -558,7 +590,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
     }),
 
-    armorgear: Object.freeze({
+    armor: Object.freeze({
         // Quantity is always one, so the specification refuses the key rather
         // than defaulting it.
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR]),
@@ -573,7 +605,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         data: Object.freeze([TEMPLATE_PRIORITY]),
     }),
 
-    concoctiongear: Object.freeze({
+    concoction: Object.freeze({
         subTypes: Object.freeze(["mundane", "exotic", "elixir"]),
         data: Object.freeze([
             TEMPLATE_PRIORITY,
@@ -648,7 +680,7 @@ export const NOTE_VOCABULARY = Object.freeze({
         ]),
     }),
 
-    projectilegear: Object.freeze({
+    projectile: Object.freeze({
         subTypes: Object.freeze(["none", "arrow", "bolt", "bullet", "dart", "other"]),
         data: Object.freeze([TEMPLATE_PRIORITY, ...GEAR, QUANTITY]),
     }),
@@ -711,6 +743,57 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     macro: Object.freeze({ data: Object.freeze([]) }),
 
+    // Foundry's `Folder`, and the last document this package compiled from
+    // bespoke configuration rather than from a note (#256). It declares no
+    // system-block fields, like a bundle: a `Folder` is a core Foundry
+    // document, so its address carries the `none` system segment and
+    // everything it says is a `data` property.
+    //
+    // It carries **no prose**, which is the decision #256 left open: a folder
+    // is structure, not content, so it wants no documentation journal and takes
+    // no part in `docEntryTypes`.
+    folder: Object.freeze({
+        data: Object.freeze([
+            {
+                name: "parent",
+                ...LINK_BY_PACK,
+                describe:
+                    "The folder this one sits in, as an address — or one " +
+                    "address per pack, keyed by pack name with `default` for " +
+                    "the rest. Unset at the root. A dead address is a " +
+                    "dead-address finding and a cycle is refused, per pack.",
+            },
+            {
+                name: "color",
+                ...TEXT,
+                describe: "The folder's colour, as a CSS hex code. Unset for Foundry's default.",
+            },
+        ]),
+    }),
+
+    // Foundry's `Adventure`, named for what it is rather than what Foundry
+    // calls it: a set of documents taken as a unit. The document is an
+    // installer — it carries copies, and importing one creates or updates each
+    // document in the world — which is what separates a bundle from a folder,
+    // a live grouping that persists in the pack (#259).
+    //
+    // How many Adventures a bundle makes is decided by its system blocks, as
+    // for every other type, and not by a property: an `Adventure` has no
+    // `system` field, so a bundle spanning two systems is two documents, and
+    // the pack each is written to is what carries the system.
+    bundle: Object.freeze({
+        data: Object.freeze([
+            {
+                name: "contents",
+                ...LINKS,
+                describe:
+                    "The documents the Adventure holds, as addresses. Empty " +
+                    "when unstated. A document of neither `none` nor the " +
+                    "system being compiled is left out rather than failing.",
+            },
+        ]),
+    }),
+
     lore: Object.freeze({
         subTypes: Object.freeze([
             "cosmology",
@@ -888,9 +971,9 @@ export function typeCharsetMessage(type) {
     return (
         `content type "${type}" is not an address segment — a type is letters ` +
         `and digits only (${ADDRESS_SEGMENT_PATTERN.source}), the same charset ` +
-        `a shortcode is held to. A type is the first segment of every address ` +
-        `("type-shortcode"), so a hyphenated one is read back as two segments ` +
-        `and resolves to nothing`
+        `a shortcode is held to. A type is a segment of every address, and the ` +
+        `first of the short form an author writes ("type-shortcode"), so a ` +
+        `hyphenated one is read back as two segments and resolves to nothing`
     );
 }
 
@@ -948,7 +1031,7 @@ assertVocabularyCharset(NOTE_VOCABULARY);
  *   one, and is why the lint makes no claim rather than refusing every key.
  */
 export function dataFields(type, vocabulary = NOTE_VOCABULARY) {
-    return vocabulary?.[type]?.data;
+    return vocabulary?.[currentType(type)]?.data;
 }
 
 /**
@@ -962,7 +1045,7 @@ export function dataFields(type, vocabulary = NOTE_VOCABULARY) {
  *   it has no `subType` at all — see {@link TypeVocabulary}.
  */
 export function subTypes(type, vocabulary = NOTE_VOCABULARY) {
-    const entry = vocabulary?.[type];
+    const entry = vocabulary?.[currentType(type)];
     if (!entry || !Object.hasOwn(entry, "subTypes")) return undefined;
     return entry.subTypes;
 }

package/engine/pack-config.mjs

@@ -168,6 +168,10 @@ const ITEM_BUILDER_REGISTRIES = Object.freeze({
         /** @type {{ ITEM_BUILDERS: Record<string, unknown> }} */ (
             require("../sohl/item-builders.mjs")
         ).ITEM_BUILDERS,
+    hm3: () =>
+        /** @type {{ HM3_ITEM_BUILDERS: Record<string, unknown> }} */ (
+            require("../hm3/item-builders.mjs")
+        ).HM3_ITEM_BUILDERS,
 });
 
 /**

package/engine/pack-router.mjs

@@ -220,6 +220,29 @@ export function createPackRouter(packs) {
             return [...(byType.get(docType) ?? [])];
         },
 
+        /**
+         * The systems declared by the packs of one document type.
+         *
+         * What a pass asks to tell a note that belongs to *another system's*
+         * pass from one that is simply missing this system's block (#139). A
+         * repository feeding two systems declares an Item pack per system, so
+         * a note carrying only `hm3:` is not an incomplete SoHL note — it is a
+         * note the HM3 pass will claim, and the SoHL pass has to pass over it
+         * rather than fail it.
+         *
+         * @param {string} docType - The Foundry document type.
+         * @returns {string[]} The declared systems, deduplicated, in
+         *   configured order. Empty where no pack of the type names one.
+         */
+        systemsOfType(docType) {
+            const out = [];
+            for (const name of byType.get(docType) ?? []) {
+                const system = byName.get(name)?.system;
+                if (system && !out.includes(system)) out.push(system);
+            }
+            return out;
+        },
+
         /**
          * The pack of a type that receives notes declaring none.
          *

package/engine/retired-fields.mjs

@@ -23,8 +23,8 @@
  *
  * `package:` is retired the same way and is refused from `note-package.mjs`,
  * where the concept it belonged to still lives. `draft:`, the top-level
- * `aliases:` and `section:` have no such home — there is no surviving concept
- * any of them was part of — so they are refused here.
+ * `aliases:`, `section:` and `traits:` have no such home — there is no
+ * surviving concept any of them was part of — so they are refused here.
  *
  * **What `draft:` did (#69).** It excluded a note from the compiled packs, from
  * the link manifest and from a consuming site build. Nothing reported the
@@ -56,6 +56,23 @@
  * reserved.test.ts` pins that equivalence so a future reader cannot be added
  * by accident.
  *
+ * **What `traits:` did (#291).** It held a being's own description — gender,
+ * species, age, birthday, height, weight, frame and `appearance.*` — at the
+ * note's top level. The content format gives those a home: `data:`, the closed
+ * container for a subject's type-specific facts, which `being` declares every
+ * one of them in. #128 moved all 2,533 notes that carried one, across four
+ * repositories, and this is the third step of that retirement.
+ *
+ * Refusing it matters more than refusing an ordinary dead key, because top
+ * level is *deliberately open*: an unrecognised key there is passed through to
+ * Hugo, so a stray `traits:` would not be ignored loudly but would arrive on
+ * the page as a theme parameter, checked by nothing. The whole argument for
+ * `data:` being closed is the argument for refusing this.
+ *
+ * `sohl.traits` is a different field that shares the name — `projectilegear`
+ * declares one, and the theme's gear sidebar reads it — so the refusal is
+ * anchored at column 1 and never reaches inside a system block.
+ *
  * **A field retired in favour of another is a third case (#142).** `draft:` and
  * `package:` were retired outright: nothing replaced them, so no value made
  * writing one right and refusal was the only honest answer. A *renamed* field
@@ -67,6 +84,15 @@
  * the refusal come later, once no tree writes it. See
  * {@link RETIRED_FIELD_ALIASES}.
  *
+ * **A retired *position* is the same case, and reads the same (#305).** A field
+ * whose shared source moved under `data:` is not renamed — `data.species` and
+ * `hm3.species` are one field written in two places — but the retirement has
+ * the identical shape: both are read, the one the note carries wins, and the
+ * legacy in-block key is reported by {@link legacyKeyMessage} so the sweep has
+ * something to count down. Which position a value came from is
+ * {@link module:engine/system-block.resolveFieldValue}'s answer; this module
+ * only says what an author is told about it.
+ *
  * @module
  */
 
@@ -289,6 +315,65 @@ export function assertNoSectionField(fm, { file, absPath } = {}) {
     throw err;
 }
 
+/**
+ * What a note writing a top-level `traits:` block is told.
+ *
+ * The message states the **mapping**, not just the destination, because three
+ * of the keys reshaped as well as moved: the block nested its measurements
+ * where the format flattens them. A bare "write `data:` instead" would send an
+ * author to author `data.height: {m: 1.78}`, which is a declared key holding an
+ * undeclared shape.
+ *
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function traitsRetiredMessage(file) {
+    return (
+        "`traits:` is a retired frontmatter block — move it into `data:`" +
+        (file ? ` — ${file}` : "") +
+        ". A being's own description belongs in the closed container the " +
+        "content format declares, where `being` declares every one of its " +
+        "keys; at the top level it was passed through to the page unchecked, " +
+        "so a misspelling became a theme parameter rather than a finding. " +
+        "`gender`, `species`, `age`, `birthday` and `appearance.*` move " +
+        "unchanged; three reshape — `traits.height.m` becomes `data.height` " +
+        "(metres), `traits.weight.kg` becomes `data.weight` (kilograms), and " +
+        "`traits.build.frame` becomes `data.frame`"
+    );
+}
+
+/**
+ * Refuse a note that declares a top-level `traits:` block at all.
+ *
+ * Presence is the whole test, as it is for `draft:` and `aliases:`: an empty
+ * `traits:` is still a note claiming a block that no longer exists.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note declares the block.
+ */
+export function assertNoTraitsField(fm, { file, absPath } = {}) {
+    if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "traits")) return;
+
+    const err = new Error(`${traitsRetiredMessage(file)}.`);
+    // Anchored at column 1. `sohl.traits` is a *different field that shares the
+    // name* — `projectilegear` declares one and the theme's gear sidebar reads
+    // it — so a finding about the top-level block must never open on it.
+    const position = locateFrontmatterKey(absPath, "traits", undefined, { topLevel: true });
+    if (position) err.position = position;
+    throw err;
+}
+
 /**
  * A frontmatter key's position in a note's file, or nothing.
  *
@@ -335,6 +420,19 @@ export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel
  * `image` is retired on a map — which declares `img` — and remains an unknown
  * key anywhere else.
  *
+ * **`templatePriority` (#266).** The number that decides which of several
+ * competing templates the Create dialog offers was called `archetype`, and
+ * `archetypes` — one letter apart — is a list of what *sort* a character is.
+ * A priority and a taxonomy cannot be told apart by a plural `s`, so the
+ * priority takes the name that says what it is. The specification already
+ * called it `templatePriority` on two of its three sides.
+ *
+ * **`relations` (SoHL#1781).** The field holds a *map* of standings, one per
+ * affiliation — its own description says so, and `resolveRelation` has always
+ * read it that way. `relation` named the many as one, which every author had to
+ * read past. Only `affiliation` declares the field, so the alias is reported
+ * there and the old spelling stays an ordinary unknown key everywhere else.
+ *
  * **`img` (#142).** Every note type names its artwork `img`, at the note's top
  * level, and resolves it the same way. A map alone named its background art
  * `image` and read it out of the `sohl:` block — two spellings for one idea,
@@ -345,7 +443,11 @@ export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel
  *
  * @type {Readonly<Record<string, string>>}
  */
-export const RETIRED_FIELD_ALIASES = Object.freeze({ img: "image" });
+export const RETIRED_FIELD_ALIASES = Object.freeze({
+    img: "image",
+    templatePriority: "archetype",
+    relations: "relation",
+});
 
 /**
  * What a note writing a renamed field is told, in one place.
@@ -373,6 +475,38 @@ export function retiredAliasMessage(retired, current, file) {
     );
 }
 
+/**
+ * What a note writing a field at its **legacy in-block position** is told.
+ *
+ * The same three-step retirement `retiredAliasMessage` announces, applied to a
+ * *position* rather than a spelling (#305). A field whose shared source moved
+ * under `data:` keeps reading the key its block still carries, that read wins,
+ * and it is reported here so a sweep has something to count down — without it,
+ * moving a field into `data:` would be a flag day across every repository that
+ * authors it.
+ *
+ * It names the block, because the key is `hm3.species` and not `species`: an
+ * author told to move "`species`" has two regions to guess between.
+ *
+ * @param {string} block - The system block the key was written in.
+ * @param {{name?: string, legacyKey?: string}} field - The declaration, which
+ *   names both positions.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function legacyKeyMessage(block, field, file) {
+    const legacy = `${block}.${field.legacyKey}`;
+    return (
+        `\`${legacy}:\` is the legacy position of the shared \`${field.name}:\` ` +
+        `— write it under \`data:\` instead` +
+        (file ? ` — ${file}` : "") +
+        `. Both are read and \`${legacy}\` wins, so the note compiles ` +
+        `identically either way; the in-block key is removed in a later release`
+    );
+}
+
 /**
  * Whether a note writes the retired spelling of a field, wherever it put it.
  *

package/engine/scenes.mjs

@@ -51,10 +51,24 @@ import fs from "fs";
 import path from "path";
 import log from "loglevel";
 
-import { walkMarkdownTree, sohlField, resolveName, slugify, defaultStats } from "./helpers.mjs";
+import {
+    parseMarkdownFile,
+    sohlField,
+    resolveName,
+    slugify,
+    defaultStats,
+    folderField,
+} from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
+// What an Adventure member may carry is one rule, and the module that owns the
+// Adventure states it: the scenes pass bundles its pinned places, and the
+// bundles pass compiles a note into one (#259).
+import { stripAdventureKeys } from "./bundle-notes.mjs";
 import { buildJournalEntry, splitPages, journalPageId } from "./journals.mjs";
 import { compendiumUuid, makeId, packForType } from "./ids.mjs";
+// The record accessors only — see `engine/index-records.mjs` for why they live
+// apart from the index that builds them (#243).
+import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
 import { packRouter } from "./pack-router.mjs";
 import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
@@ -109,28 +123,6 @@ export function collectKnownActionNames(repoRoot) {
     return names;
 }
 
-/**
- * Strip the LevelDB keys from a document tree.
- *
- * An Adventure's members are inline source data in a `SetField`, not sublevel
- * documents, so they carry no `_key` — the CLI's hierarchy does not recurse
- * into an adventure, and Foundry's schema has no such field to hold it.
- *
- * @param {*} value - A document, array, or scalar.
- * @returns {*} The same shape with every `_key` removed.
- */
-function stripKeys(value) {
-    if (Array.isArray(value)) return value.map(stripKeys);
-    if (value && typeof value === "object") {
-        return Object.fromEntries(
-            Object.entries(value)
-                .filter(([k]) => k !== "_key")
-                .map(([k, v]) => [k, stripKeys(v)]),
-        );
-    }
-    return value;
-}
-
 export class Scenes extends BasePackCompiler {
     static id = "scenes";
     static label = "map";
@@ -148,11 +140,12 @@ export class Scenes extends BasePackCompiler {
     constructor({
         contentBase,
         dest,
+        skipDirectories,
         companionDests = {},
         folderResolver = () => null,
         repoRoot = process.cwd(),
     }) {
-        super({ contentBase, dest, folderResolver });
+        super({ contentBase, dest, folderResolver, skipDirectories });
         if (!companionDests.adventures) {
             throw new Error("Scenes compiler requires an `adventures` companion destination");
         }
@@ -179,15 +172,41 @@ export class Scenes extends BasePackCompiler {
      *
      * @returns {{maps: Array<object>, effectsByAddress: Map<string, object>}}
      */
+    /**
+     * The router this pass resolves pack names through.
+     *
+     * `generatePack` hands every pass the one router the compile resolved, and
+     * that is the answer whenever a real compile is running — a second router
+     * is a second answer to where a document landed, built from whichever
+     * configuration the working directory offers (#243). A compiler
+     * constructed directly, as a consumer's or a test's is, has none, and falls
+     * back exactly as `prepare` falls back to deriving its own corpus.
+     *
+     * @returns {object} The pack router.
+     */
+    get #packRouter() {
+        return this.router ?? packRouter();
+    }
+
     #collect() {
         const maps = [];
         const effectsByAddress = new Map();
-        for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(this.contentBase)) {
+        // The corpus this compile derived once, not a walk of this pass's own
+        // (#243) — and a note is opened only when this pass needs its *prose*,
+        // which for a map note means three files in `sohl` rather than 1,685.
+        for (const record of this.corpus.records) {
+            if (!isNoteRecord(record)) continue;
             // No retired-field test: this pass's own walk — the shared compile
             // loop — is where a note still declaring `package:` (#56) or
             // `draft:` (#69) is reported, once. Repeating either check here
             // would double the diagnostic or throw past it. A refused note is
             // indexed and then never compiled, so it reaches no document.
+            const fm = authoredFrontmatter(record);
+            const absPath = noteFile(this.contentBase, record);
+            // The id is the index's, derived against the configuration this
+            // build resolved (#270, #243) — it was derived here through
+            // `resolveNoteId(fm)` with no package, which falls back to the
+            // ambient one. What remains unset is a file with no address.
             if (!fm || !fm.id) continue;
             if (fm.shortcode && Array.isArray(fm.effects) && fm.effects.length) {
                 effectsByAddress.set(`${fm.type}-${fm.shortcode}`, {
@@ -196,12 +215,17 @@ export class Scenes extends BasePackCompiler {
                     // Where the owning item landed, so a region behaviour's
                     // effect reference addresses the right pack when a
                     // repository ships several of one type (#1566).
-                    pack: packRouter().resolveOrNull(fm, packForType(fm.type).docType),
+                    // This compile's router, not a freshly built one: a
+                    // second router is a second answer to where the document
+                    // landed, resolved from the working directory (#243).
+                    pack: this.#packRouter.resolveOrNull(fm, packForType(fm.type).docType),
                     effects: fm.effects,
                 });
             }
             if (!isMapType(fm.type)) continue;
-            maps.push({ fm, body, absPath });
+            // Read here, and only here: the index carries no note body, and a
+            // map's prose is what this pass compiles into its Scene.
+            maps.push({ fm, body: parseMarkdownFile(absPath).body, absPath });
         }
         return { maps, effectsByAddress };
     }
@@ -340,8 +364,8 @@ export class Scenes extends BasePackCompiler {
      */
     #pageIds(markdown, entryId, name) {
         const pageIds = new Map();
-        splitPages(markdown, name).forEach((page, index) => {
-            const id = journalPageId(entryId, page, index);
+        splitPages(markdown, name).forEach((page) => {
+            const id = journalPageId(entryId, page);
             if (page.anchorSlug) pageIds.set(page.anchorSlug, id);
             const slug = slugify(page.name);
             if (slug && !pageIds.has(slug)) pageIds.set(slug, id);
@@ -384,7 +408,8 @@ export class Scenes extends BasePackCompiler {
         // shared `docEntryTypes` arrangement (#1514) — so neither
         // pass has to read the other's output.
         const entryId = hasBody ? itemDocEntryId(fm.id) : undefined;
-        const folder = this.folderResolver(sohlField(fm, "folder", null));
+        const { value: authoredFolder, isAddress: folderIsAddress } = folderField(fm);
+        const folder = this.folderResolver(authoredFolder, { isAddress: folderIsAddress });
         // The retired spelling of the background art, reported where an author
         // meets it soonest — every consumer runs the compile, and not every
         // one runs the lint (#142). Located by reading the note back, which is
@@ -406,7 +431,8 @@ export class Scenes extends BasePackCompiler {
             // A map note's prose is a derived JournalEntry: it lands in the
             // default JournalEntry pack, not in whichever Scene pack the map
             // itself was routed to (#1566).
-            journalPack: packRouter().defaultOf("JournalEntry"),
+            // This compile's router, as everywhere else in this pass (#243).
+            journalPack: this.#packRouter.defaultOf("JournalEntry"),
             pageIds: hasBody ? this.#pageIds(markdown, entryId, name) : new Map(),
             knownActions: this.knownActions,
             warnings,
@@ -431,7 +457,13 @@ export class Scenes extends BasePackCompiler {
                     name,
                     markdown,
                     leadName: name,
-                    folder: sohlField(fm, "folder", null),
+                    // As in the journals pass: an id crosses packs verbatim,
+                    // an address resolves in the pack that emits it — which is
+                    // what makes the folder materialise there too (#257).
+                    folder:
+                        folderIsAddress ?
+                            this.folderResolver(authoredFolder, { isAddress: true })
+                        :   authoredFolder,
                     flags: fm.flags,
                 })
             :   null;
@@ -448,8 +480,8 @@ export class Scenes extends BasePackCompiler {
             });
         }
         const place = this.places.get(placeKey);
-        place.scenes.push(stripKeys(scene));
-        if (journal) place.journal.push(stripKeys(journal));
+        place.scenes.push(stripAdventureKeys(scene));
+        if (journal) place.journal.push(stripAdventureKeys(journal));
         if (Object.keys(fm.sohl?.locations ?? {}).length) {
             place.pinned = true;
         }