@heroiclands/package-build 22.14.1 → 22.14.3

package/docs/getting-started.md

@@ -35,6 +35,13 @@ and this tutorial links to them rather than repeating them:
 | [`project-setup.md`](project-setup.md)   | The files a repository carries beyond the configuration, and the script wiring. |
 | [`api.md`](api.md)                       | The programmatic surface, for a repository with a build script of its own.      |
 
+An editor can render one note from its current buffer through the
+[`engine.sitePreview` API](api.md#enginesitepreview). The context reads saved
+notes and dependency indexes once, while each render overlays the active note's
+text and frontmatter. It returns generated Markdown and frontmatter for an HTML
+preview, or located findings if the page cannot be rendered. The editor keeps
+its own preview artifact and calls `refresh()` after a save.
+
 ## The shape of what you are building
 
 Nine files, and a directory the build writes:
@@ -270,9 +277,9 @@ requires it. It compiles to a page and to no Foundry document.
 
 ```markdown
 ---
-type: homepage
 shortcode: root
-title: The Acme Bestiary
+name: { full: The Acme Bestiary }
+type: homepage
 description: Creatures of the reed flats, their habits and their hides.
 ---
 
@@ -286,11 +293,10 @@ who hunt it.
 
 ```markdown
 ---
+shortcode: marshdrake
+name: { full: Marsh Drake }
 type: lore
 subType: bestiary
-name:
-  full: Marsh Drake
-shortcode: marshdrake
 description: A wingless drake of the reed flats, hunted for its hide and feared for its patience.
 ---
 
@@ -317,20 +323,45 @@ directory has no bearing on which pack it lands in. `subType:` narrows it —
 `(type, subType)` is what each game system maps onto its own document type.
 
 **`shortcode:` is the note's address.** Cross-references are written
-`[[lore-marshdrake]]` — the type and the shortcode — and resolve to whatever
+`[[lore-marshdrake|Marsh Drake]]` — the type, shortcode, and readable label — and resolve to whatever
 that note compiles into, in whatever system is being compiled. A shortcode is
 identity: renaming one breaks every link into it.
 
 **`name.full` is the document name and the published URL**, derived by one
 shared rule. There is no authored slug anywhere in this toolchain.
 
-**Frontmatter has three regions and only one of them is open.** Top-level keys
-(`type`, `shortcode`, `description`, `tags`, and anything else) are copied into
-the generated web page, so an unrecognised one is a theme parameter rather than
-an error. A `data:` block and a `sohl:` / `hm3:` block are closed: a misspelled
-key there is a finding that names the key you meant.
+**Frontmatter has three closed regions.** Top-level keys identify the note and
+describe its publication; `data:` holds shared facts; `sohl:` and `hm3:` hold
+system-specific facts. An unrecognised key is an error rather than a site
+parameter. The formatter keeps the allowed top-level keys in their required
+order.
 [`content-format.md`](content-format.md) is the specification.
 
+**A setting guide is a `doc` that orients a reader to a place or setting.** It
+gives a usable overview of areas, peoples, institutions, and daily life, then
+links to the detailed notes. Use `subType: settingguide` for that entry point;
+`concept` explains one subject, `reference` serves lookup, and `userguide`
+explains the Foundry controls. For example, a guide at
+`assets/content/Guides/Reed_Flats.md` can begin:
+
+```markdown
+---
+shortcode: reedflatsguide
+name: { full: The Reed Flats Guide }
+type: doc
+subType: settingguide
+description: A starting point for adventures in the Reed Flats.
+---
+
+The river trade links the settlements of the Reed Flats. Their routes and
+customs give visitors a way into the region. See [[lore-reedfolk|Reed Folk]]
+for the people who guide those journeys.
+```
+
+The guide can include SQL tables for lists drawn from indexed notes and
+`:::secret` blocks for GM passages. Its address is
+`doc-reedflatsguide`, following the same rule as every `doc` note.
+
 An image stands in its own paragraph. Its directive accepts a named size and a
 position together:
 

package/docs/project-setup.md

@@ -27,7 +27,7 @@ acme-bestiary/
 │   ├── ISSUE_REPORTING.md        # §3 lists the same labels
 │   └── workflows/
 ├── assets/
-│   └── content/                  # authored notes — an Obsidian vault
+│   └── content/                  # authored Markdown notes
 ├── lang/
 │   └── en.json
 ├── src/                          # module JavaScript, if the package has any
@@ -55,11 +55,10 @@ The two that matter when something is wrong are `build/packs-json/`, which is
 the compiled document before Foundry ever sees it, and `build/stage/`, which is
 exactly what ships.
 
-**`assets/content/` is opened as an Obsidian vault.** There is no export step
-and no vault environment variable: the notes in the repository are the source,
-and a plain checkout builds. Dataview renders the content tables live while
-authoring, which is why the tree is arranged for humans even though `type:`
-rather than location is what routes a note.
+**`assets/content/` holds the source notes.** Edit the Markdown and YAML
+frontmatter directly; a plain checkout builds without an export step. The
+tree is arranged for readers and authors, while `type:` determines how each
+note compiles.
 
 ## `package.json`
 

package/engine/address.mjs

@@ -491,11 +491,9 @@ export function readCanonicalKey(key) {
  * confidently they mark a value as qualified:
  *
  * - **`type-shortcode`** and its qualified forms — the canonical spelling.
- *   Obsidian reads `/` inside a wikilink as a *path* and resolves it against the
- *   vault's folders, so a slash-qualified link is a broken link in the editor
- *   where the content is authored.
- * - **`type/shortcode`** — resolved so that a link written before the vault
- *   migrated does not silently die. A slash is *unconditionally* a qualifier:
+ *   The hyphenated form is portable across Markdown editors and renderers.
+ * - **`type/shortcode`** — an accepted qualified spelling. A slash is
+ *   *unconditionally* a qualifier:
  *   nothing else uses one, so an unknown type before it is reported rather than
  *   guessed at. The split is at the **last** slash.
  *

package/engine/asset-bindings.mjs

@@ -0,0 +1,66 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { isAddressSegment } from "./address-charset.mjs";
+import { canonicalKey } from "./content-address.mjs";
+import { loadForeignIndexes, metadataRelationships } from "./metadata-index.mjs";
+
+/** Files under a configured staging root, without provenance sidecars. */
+function assetFiles(root) {
+    if (!fs.existsSync(root)) return [];
+    const files = [];
+    const visit = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory()) visit(file);
+            else if (entry.isFile() && !entry.name.endsWith(".yaml")) files.push(file);
+        }
+    };
+    visit(root);
+    return files;
+}
+
+/** Check configured foreign Address bindings against fetched indexes. */
+export function checkForeignAssetBindings(config, { foreignIndex, assets } = {}) {
+    const copies = (assets ?? config.packageBuild?.assets ?? []).filter((asset) => asset.bindsTo);
+    if (!copies.length) return [];
+    const relationships = metadataRelationships(config);
+    const active = copies.filter(({ bindsTo }) =>
+        relationships.some((rel) => rel.id === bindsTo.package),
+    );
+    if (!active.length) return [];
+    const fetched = foreignIndex ? null : loadForeignIndexes(config, [config.contentPackage]);
+    const foreign = foreignIndex ?? fetched.index;
+    for (const { bindsTo } of active) {
+        if (fetched && !fetched.packages.has(bindsTo.package))
+            return [
+                {
+                    file: "package-build.config.yaml",
+                    severity: "error",
+                    message: `asset binding index for ${bindsTo.package} is unavailable; run content-build deps fetch`,
+                },
+            ];
+    }
+    const findings = [];
+    for (const { from, bindsTo } of active) {
+        const root = path.resolve(config.rootDir, from);
+        if (path.relative(config.rootDir, root).startsWith(".."))
+            throw new Error(`packageBuild.assets source ${from} escapes the repository`);
+        for (const file of assetFiles(root)) {
+            const shortcode = path.parse(file).name;
+            const key =
+                isAddressSegment(shortcode) ?
+                    canonicalKey(bindsTo.package, bindsTo.system ?? "note", bindsTo.type, shortcode)
+                :   null;
+            if (!key || !foreign.has(key))
+                findings.push({
+                    file: path.relative(config.rootDir, file),
+                    severity: "error",
+                    message: `asset binding ${key ?? JSON.stringify(shortcode)} resolves to no ${bindsTo.type} in ${bindsTo.package}`,
+                });
+        }
+    }
+    return findings;
+}

package/engine/calendar-notes.mjs

@@ -82,6 +82,27 @@ export const CALENDAR_SUBTYPE = "calendar";
  */
 export const INVARIANT_SUBTYPES = Object.freeze(["world", "celestial"]);
 
+/** Calendaria's display locations that a calendar note can format. */
+export const CALENDAR_DATE_FORMAT_KEYS = Object.freeze([
+    "short",
+    "long",
+    "full",
+    "time",
+    "weekHeader",
+    "yearHeader",
+    "yearLabel",
+    "crossCalendar",
+]);
+
+/** Bare date tokens Calendaria substitutes inside authored format strings. */
+export const CALENDAR_FORMAT_TOKENS = Object.freeze(
+    new Set(
+        "YYYY YY Y MMMM MMM MM Mo M EEEEE EEEE EEE EE E dddd ddd dd Do DDD DD D d e GGGG GGG GG G QQQQ QQQ QQ Q zzzz z ww w W HH H hh h mm m ss s A a".split(
+            " ",
+        ),
+    ),
+);
+
 /**
  * The `data:` keys a calendar note may write — the closed list, in authored
  * order.
@@ -129,6 +150,12 @@ export const CALENDAR_FIELDS = Object.freeze([
             "The year-counts kept in this calendar. A date names one by writing " +
             "`<calendar shortcode>.<era shortcode>`.",
     },
+    {
+        name: "dateFormats",
+        shape: "map of short, long, full, time, weekHeader, yearHeader, yearLabel, crossCalendar strings",
+        kind: "map",
+        describe: "How this calendar writes dates and time in each display context.",
+    },
 ]);
 
 /**
@@ -336,6 +363,51 @@ function atData(note, keyPath, severity, message) {
     };
 }
 
+/** Check each authored format slot and every unescaped letter run in it. */
+export function checkCalendarDateFormats(note) {
+    const formats = dataOf(note).dateFormats;
+    if (formats === undefined || formats === null) return [];
+    if (typeof formats !== "object" || Array.isArray(formats)) return [];
+    const findings = [];
+    for (const [slot, value] of Object.entries(formats)) {
+        if (!CALENDAR_DATE_FORMAT_KEYS.includes(slot)) {
+            findings.push(
+                atData(
+                    note,
+                    ["dateFormats", slot],
+                    "error",
+                    `data.dateFormats.${slot} is not a calendar display format; choose ${CALENDAR_DATE_FORMAT_KEYS.join(", ")}`,
+                ),
+            );
+            continue;
+        }
+        if (typeof value !== "string") {
+            findings.push(
+                atData(
+                    note,
+                    ["dateFormats", slot],
+                    "error",
+                    `data.dateFormats.${slot} must be a string`,
+                ),
+            );
+            continue;
+        }
+        const bare = value.replace(/\[[^\]]*\]|\{[^}]*\}/g, " ");
+        for (const run of bare.match(/\p{L}+/gu) ?? []) {
+            if (CALENDAR_FORMAT_TOKENS.has(run)) continue;
+            findings.push(
+                atData(
+                    note,
+                    ["dateFormats", slot],
+                    "error",
+                    `data.dateFormats.${slot} has unescaped letter run ${JSON.stringify(run)}; write literal words in brackets, or use a Calendaria date token`,
+                ),
+            );
+        }
+    }
+    return findings;
+}
+
 /**
  * Check a `place` note's world facts.
  *
@@ -488,6 +560,7 @@ export function checkCalendarNote(note, { index } = {}) {
 
     findings.push(...checkMonthSum(note, index));
     findings.push(...checkEraShortcodes(note));
+    findings.push(...checkCalendarDateFormats(note));
     return findings;
 }
 
@@ -747,6 +820,7 @@ export function compileCalendar({ note, invariants, contentPackage }) {
         epochDayOffset:
             epoch && months.length ? dayOfYear(months, epoch.month ?? 1, epoch.day ?? 1) - 1 : 0,
         eras: eraEntries(data.eras),
+        dateFormats: data.dateFormats,
         moons: moons ?? undefined,
         metadata: written({
             id: shortcode || undefined,

package/engine/changelog-lint.mjs

@@ -56,10 +56,10 @@ const LABEL_LINE_RE = /^\*\*([^*]+)\*\*/;
 const COMMIT_HASH_RE = /^-\s+([0-9a-fA-F]{7,40})(?=[:\s]|$)/;
 
 /**
- * An issue or pull-request reference: `#123`, `owner/repo#123`.
+ * An issue or pull-request reference, with or without an owner and repository.
  *
  * No leading `\b` — `#` is not a word character, so a boundary assertion
- * immediately before it never matches the ordinary case of a bare `#123`
+ * immediately before it never matches a bare issue reference
  * preceded by whitespace or punctuation.
  */
 const ISSUE_REF_RE = /(?:[\w.-]+\/[\w.-]+)?#\d+\b/g;

package/engine/content-index.mjs

@@ -87,7 +87,7 @@
  */
 
 import { isAddressSegment } from "./address-charset.mjs";
-import { positionOfYamlPath } from "./diagnostics.mjs";
+import { formatDiagnostic, positionOfYamlPath } from "./diagnostics.mjs";
 import {
     decodeNoteAddresses,
     decodeIndexAddresses,
@@ -101,6 +101,7 @@ import unidecode from "unidecode";
 
 import { metadataFileName } from "./metadata-index.mjs";
 import { collectAssetRecords } from "./asset-index.mjs";
+import { checkForeignAssetBindings } from "./asset-bindings.mjs";
 import { addressSlug, canonicalKey } from "./content-address.mjs";
 import { ownDocumentSystem } from "./address.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
@@ -360,6 +361,13 @@ function foundryEntries({ frontmatter, address, body, manifest }) {
 
 function foundryBlock(entry, system) {
     if (!entry) return null;
+    if (entry.systemUuids && Object.keys(entry.systemUuids).length)
+        return Object.fromEntries(
+            Object.entries(entry.systemUuids).map(([targetSystem, uuid]) => [
+                targetSystem,
+                { uuid },
+            ]),
+        );
     const block = {};
     if (entry.uuid) block.uuid = entry.uuid;
     if (entry.anchors) block.anchors = entry.anchors;
@@ -590,6 +598,46 @@ function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anc
     );
 }
 
+/** Derive every index record belonging to one parsed note. */
+export function indexRecordsForNote({
+    frontmatter,
+    body,
+    bodyLine,
+    relPath,
+    absPath,
+    contentPackage,
+    manifest,
+    addressContext,
+}) {
+    resolveNoteId(frontmatter, { pkg: contentPackage });
+    const record = buildIndexRecord({
+        frontmatter,
+        body,
+        bodyLine,
+        relPath,
+        absPath,
+        contentPackage,
+        manifest,
+        addressContext,
+    });
+    const records = [decodeIndexAddresses(record, addressContext ?? { package: contentPackage })];
+    const address = noteAddress(frontmatter, contentPackage);
+    const doc = foundryEntries({ frontmatter, address, body, manifest })?.doc;
+    if (doc?.key && address) {
+        records.push(
+            buildDocRecord({
+                frontmatter,
+                address,
+                entry: doc,
+                file: record.file,
+                contentPackage,
+                anchors: record.anchors ?? [],
+            }),
+        );
+    }
+    return records;
+}
+
 /**
  * Read a content tree into index records, in the order they will be written.
  *
@@ -648,23 +696,20 @@ export function collectContentIndex(
     for (const { frontmatter, body, bodyLine, absPath } of notes) {
         const fm = frontmatter ?? {};
         applyComputedBeingAge(fm, present);
-        // The id the note's document is filed under, resolved before
-        // the record is built so the index publishes the address *and* the id
-        // that address derives.
-        resolveNoteId(fm, { pkg: contentPackage });
         const relPath = path.relative(contentBase, absPath);
-        let record;
         try {
-            record = buildIndexRecord({
-                frontmatter: fm,
-                relPath,
-                absPath,
-                contentPackage,
-                body,
-                bodyLine,
-                manifest,
-                addressContext,
-            });
+            records.push(
+                ...indexRecordsForNote({
+                    frontmatter: fm,
+                    relPath,
+                    absPath,
+                    contentPackage,
+                    body,
+                    bodyLine,
+                    manifest,
+                    addressContext,
+                }),
+            );
         } catch (err) {
             if (fm.shortcode && !isAddressSegment(fm.shortcode) && err.keyPath) {
                 err.identity = { type: fm.type, shortcode: fm.shortcode };
@@ -693,26 +738,6 @@ export function collectContentIndex(
             });
             continue;
         }
-        records.push(decodeIndexAddresses(record, addressContext ?? { package: contentPackage }));
-
-        // An item note is two documents, so it is two records. Derived from
-        // the address the note *would* hold rather than from the one its
-        // record carries, because a stub withholds its own address; the second
-        // record says whether the journal beside the item was made.
-        const address = noteAddress(fm, contentPackage);
-        const doc = foundryEntries({ frontmatter: fm, address, body, manifest })?.doc;
-        if (doc?.key && address) {
-            records.push(
-                buildDocRecord({
-                    frontmatter: fm,
-                    address,
-                    entry: doc,
-                    file: record.file,
-                    contentPackage,
-                    anchors: record.anchors ?? [],
-                }),
-            );
-        }
     }
 
     if (assetsBase) {
@@ -869,6 +894,8 @@ export function emitContentIndex({ contentBase, outDir, config } = {}) {
     // the index refuse to build for a configuration that is perfectly able to
     // state one.
     const records = indexRecordsFor({ contentBase: tree, config: resolved });
+    const assetBindings = checkForeignAssetBindings(resolved);
+    if (assetBindings.length) throw new Error(assetBindings.map(formatDiagnostic).join("\n"));
     if (records.length === 0) {
         throw new Error(
             `${tree} yielded no notes, so the index would state that this ` +

package/engine/content-lint.mjs

@@ -48,8 +48,7 @@
  *
  * **There is deliberately no third rule** requiring every note to repeat its
  * own `type-shortcode` address in a top-level `aliases:` list. It would serve
- * exactly one reader — **Obsidian**, so `[[type-shortcode]]` resolves in the
- * editor — and nothing in the build reads it: both resolvers parse the hyphen
+ * no build reader: both resolvers parse the hyphen
  * qualifier themselves. The field is retired, refused from
  * `retired-fields.mjs`.
  *

package/engine/content-package.mjs

@@ -46,7 +46,7 @@ import { loadPackConfig } from "./pack-config.mjs";
  * package below would differ.
  *
  * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration (#2).
+ * needs no configuration.
  *
  * @returns {string} The configured `contentPackage`.
  */
@@ -71,7 +71,7 @@ export function contentPackage() {
  * written — fails the build if this value and the manifest's `id` ever drift.
  *
  * An accessor rather than a hoisted constant, so that importing this module
- * needs no configuration (#2).
+ * needs no configuration.
  *
  * @returns {string} The configured `foundryPackage`.
  */

package/engine/content-tables.mjs

@@ -15,7 +15,7 @@ import { completeAddress, renderAddress, isAddressTuple } from "./address.mjs";
 import { contentPackage } from "./content-package.mjs";
 
 /**
- * Generated content tables — Obsidian **Dataview** `TABLE` queries.
+ * Generated content tables from fenced `dataview` `TABLE` queries.
  *
  * A catalog table (every cloth armour, every animal's abilities) is data that
  * already lives in the frontmatter of the notes it describes. Authoring such a
@@ -30,13 +30,9 @@ import { contentPackage } from "./content-package.mjs";
  * SORT name.full ASC
  * ```
  *
- * The content notes live in an **Obsidian vault**, where that block is rendered
- * live by the Dataview plugin. At build time this module renders the same query
- * against the same frontmatter and replaces the block with a markdown table, so
- * an author sees in Obsidian what the build ships. Both content builds run it —
- * the pack compilers (Foundry journals/items/actors) and the knowledgebase — so
- * one authored query yields the same table in the vault, in Foundry, and on the
- * knowledgebase.
+ * The build evaluates the query against note frontmatter and replaces the
+ * block with a Markdown table. Pack journals and site pages read the same
+ * generated table from the authored query.
  *
  * The emitted table is **markdown**, not HTML, and it is expanded *before*
  * wikilink resolution: a cell may therefore carry `[[type/shortcode|Text]]`,

package/engine/folder-notes.mjs

@@ -174,8 +174,7 @@ function folderFields(fm) {
  * An authored `parent` with any wikilink brackets and label stripped.
  *
  * The specification types `parent` as an `Address`, written bare — but
- * `[[address]]` is what an author reaches for,
- * and Obsidian wrote that form for years. Accepting both costs one regex and
+ * `[[address]]` is also a recognizable link form. Accepting both costs one regex and
  * removes a failure whose message would have to explain the difference.
  *
  * @param {string|null} value - As authored.

package/engine/foundry-entries.mjs

@@ -163,7 +163,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
     // A published address must name the pack the document actually shipped in:
     // a consumer resolves the UUID verbatim, and a repository may ship several
     // packs of one type.
-    const uuidFor = (type, id, routeFm) => {
+    const uuidFor = (type, id, routeFm, system) => {
         // **A document that would be empty is not created, so nothing names
         // one.** A JournalEntry's content is the note's prose, and an empty
         // body compiles no pages, so the pass emits no entry — and a manifest
@@ -201,7 +201,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
             !id ||
             NEVER_PACKED_TYPES.has(String(type)) ||
             DERIVED_PACKED_TYPES.has(String(type)) ||
-            (routeFm && declaresNoPack(routeFm))
+            (routeFm && declaresNoPack(routeFm, system))
         ) {
             return undefined;
         }
@@ -209,7 +209,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
         const docType = routeFm ? packForType(type).docType : "JournalEntry";
         const pack =
             routeFm ?
-                packRouter.resolveOrNull(routeFm, docType)
+                packRouter.resolveOrNull(routeFm, docType, system)
             :   packRouter.defaultOf("JournalEntry");
 
         // **A system block is what makes a game document**, so a note carrying
@@ -224,14 +224,27 @@ export function entriesForNote(fm, name, address, body, ctx) {
         // and one declaring none by the fallback, which reads a single block of
         // its own.
         if (SYSTEM_DOCUMENT_CLASSES.has(docType)) {
-            const system =
-                (pack && packRouter.systemOf?.(pack)) || DEFAULT_DOCUMENT_SUBTYPES.system;
-            if (!carriesSystemBlock(routeFm, system)) return undefined;
+            const targetSystem =
+                system || (pack && packRouter.systemOf?.(pack)) || DEFAULT_DOCUMENT_SUBTYPES.system;
+            if (!carriesSystemBlock(routeFm, targetSystem)) return undefined;
         }
 
         return compendiumUuid(foundryPackageId, type, id, pack);
     };
 
+    const systemUuidsFor = (type, id) => {
+        const docType = packForType(type)?.docType;
+        if (!SYSTEM_DOCUMENT_CLASSES.has(docType)) return undefined;
+        const systems = packRouter.systemsOfType?.(docType) ?? [];
+        if (!systems.length) return undefined;
+        return Object.fromEntries(
+            systems.flatMap((system) => {
+                const uuid = uuidFor(type, id, fm, system);
+                return uuid ? [[system, uuid]] : [];
+            }),
+        );
+    };
+
     const carriesDoc =
         ctx.docEntryTypes ?
             ctx.docEntryTypes.has(String(currentType(fm.type)))
@@ -251,6 +264,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
                 url,
                 id: fm.id,
                 uuid: uuidFor(fm.type, fm.id, fm),
+                systemUuids: systemUuidsFor(fm.type, fm.id),
                 doc: docKey,
             },
             {
@@ -283,6 +297,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
             url,
             id: fm.id,
             uuid: own,
+            systemUuids: systemUuidsFor(fm.type, fm.id),
             anchors: own && fm.type === "doc" ? anchorsOf(own, fm.id, body ?? "", name) : undefined,
         },
     ];

package/engine/frontmatter-lint.mjs

@@ -24,7 +24,7 @@
  * - a **wrong type** threw deep inside a builder, or was coerced;
  * - a **misspelled property** was simply *ignored* — the builders are an
  *   allow-list, so an unrecognised `sohl:` key is dropped without a word. That
- *   is how 204 kethira mystical abilities shipped with no affiliation (#3), and
+ *   is how 204 kethira mystical abilities shipped with no affiliation, and
  *   why the silence mattered more than the missing field: an author could not
  *   tell a builder that forgot the field apart from a field that does
  *   not belong on the type at all;
@@ -312,8 +312,7 @@ function nearest(key, candidates) {
  *
  * Deliberately lenient about the spellings YAML makes ambiguous: `"12"` is a
  * number, because a quoted scalar is how a number arrives from many editors,
- * and a map authored as an empty list is a map, because Obsidian's property
- * editor serialises an emptied map that way (#8). What it rejects is a value
+ * and a map authored as an empty list has no entries, just like `{}`. What it rejects is a value
  * that cannot mean what the field is for — `weight: heavy`.
  *
  * @param {unknown} value - The authored value.
@@ -378,7 +377,7 @@ function mapEntries(value) {
  * The `data:` container a note authored.
  *
  * An emptied map arrives from the property editor as `[]` and means the same
- * thing `{}` does — this note authors no entries (#8) — so both read as an
+ * thing `{}` does — this note authors no entries — so both read as an
  * empty container rather than as a malformed one.
  *
  * @param {object} fm - The note's frontmatter.