@heroiclands/package-build 23.12.8 → 24.0.0

package/engine/wikilinks.mjs

@@ -12,26 +12,35 @@
  */
 
 /**
- * Resolve body wikilinks for Foundry packs.
+ * **The link resolver.** One authored `[[…]]` is read the same way for every
+ * target, and only the form it is written in differs: a Foundry journal gets
+ * an `@UUID[…]{label}` content link, a web page a relative URL, the book a
+ * cross-reference.
+ *
+ * Resolution is {@link resolveWikilinks}. It reads the link with the syntax
+ * module, applies the rules every target shares — a link carries a label, a
+ * same-page link names a section the page declares, a target is an address,
+ * an address names one note — and hands back a {@link ResolvedLink}: what the
+ * link names, independent of any target. The index a link is read against is a
+ * {@link LinkView}, of the pack compile's index ({@link packLinkView}) or of
+ * the site's ({@link siteLinkView}), and each target writes the resolution
+ * through its {@link LINK_WRITERS} entry. {@link convertWikilinks} is the pack
+ * compile's entry, {@link resolveWebWikilinks} the website's and the book's.
  *
  * `[[type-shortcode|Text]]` defaults to the readable `note` Address. A stated
  * game system names an Actor or Item; `none` names a systemless document.
- * Journal links can carry a heading anchor. Actor, Item and Macro links open
- * their sheets, so their anchors do not select a page.
- *
- * `doc<type>` is accepted as an input alias for the readable note Address.
- * A link with an empty label displays the target's current name.
+ * `doc<type>` names an item's readable note. A link with an empty label
+ * displays the target's current name.
  *
  * @module
  */
 
 import { resolveShortcodeReference } from "./shortcode-references.mjs";
 
-import { presentWikilink, readWikilink } from "./wikilink-syntax.mjs";
 import crypto from "crypto";
 
 import { compendiumUuid, ITEM_PACK, packForType, pageUuid, PACK_BY_TYPE } from "./ids.mjs";
-import { readCanonicalKey } from "./content-address.mjs";
+import { expandAddress, readCanonicalKey } from "./content-address.mjs";
 // The address grammar. A wikilink *contains* an Address, so what counts as one
 // is stated there and read here — the anchor and the label are this module's,
 // and the tuple inside them is not.
@@ -40,30 +49,36 @@ import {
     resolveItemDocType,
     parseAddress,
     renderAddress,
-    isAddressTuple,
     completeAddress,
     ownDocumentSystem,
 } from "./address.mjs";
+import { collectAnchors } from "./anchors.mjs";
 import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
+import { resolveEmbeds } from "./content-embeds.mjs";
+// One slug rule for the whole build — see `./content-slug.mjs`.
+import { slugify } from "./content-slug.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
-import { systemOf } from "./document-subtypes.mjs";
-import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
-// The syntax lives in `./wikilink-syntax.mjs`, so the web resolver and this
-// one cannot disagree about what counts as a link.
+// The syntax lives in `./wikilink-syntax.mjs`, beside the vocabulary of link
+// findings and the message for each, which the link checker reads too.
 import {
-    authoredLabel,
+    LINK_FINDING_REASONS,
     WIKILINK,
+    authoredLabel,
     isEventAnchor,
-    parseWikilink,
-    unlabelledLinkMessage,
+    isSamePage,
+    presentWikilink,
+    readWikilink,
 } from "./wikilink-syntax.mjs";
 
+/** The heading and anchor slug: the rule that names a page names a section. */
+export { slugify };
+
 export { ITEM_PACK, PACK_BY_TYPE, packForType };
 
 /**
- * The address grammar, under the names the link resolvers hold it by.
+ * The address grammar, under the names the link readers hold it by.
  *
  * {@link readQualifier} reads a link target as the partial Address the matchers
  * consume, and {@link resolveItemDocType} is the `doc<type>` reading it applies.
@@ -311,16 +326,55 @@ function shortcodeCase(index, problem) {
 }
 
 /**
- * How an **unresolved** link renders.
+ * A wikilink once it is resolved, before any target writes it.
+ *
+ * This is the link's **neutral form**: what it names and how it reads, with no
+ * target's syntax in it. Each target writes it through its own
+ * {@link LINK_WRITERS} entry, so one authored link reaches a Foundry journal as
+ * an `@UUID` content link, a web page as a relative URL and the book as a
+ * cross-reference, from the same resolution.
+ *
+ * @typedef {object} ResolvedLink
+ * @property {"link"|"text"|"unresolved"} kind - `link`: the target has a
+ *   destination the reader can open. `text`: the address is real and names a
+ *   note with nothing to open — a note with no single Foundry document, or one
+ *   a package publishing no pages holds — so the reader gets the words.
+ *   `unresolved`: the link is a finding, and the words are kept, marked.
+ * @property {string} text - What the reader sees.
+ * @property {string} literal - The link exactly as authored.
+ * @property {string} target - The target as authored, `""` for a link to a
+ *   section of the same page.
+ * @property {string} anchor - The `#section` named, `""` when none.
+ * @property {boolean} samePage - Whether it names a section of its own page.
+ * @property {string|undefined} address - The canonical address it names, the
+ *   same on every target; `undefined` for a same-page link and for a target
+ *   that is not an address.
+ * @property {string} [uuid] - The Foundry document or page it opens.
+ * @property {string} [href] - The URL it opens on the web and in the book,
+ *   fragment included.
+ * @property {boolean} draft - Whether it names a note tagged `draft`.
+ * @property {object} [destination] - What it resolved to: an index entry,
+ *   which decides whether the reference is concealed.
+ * @property {object} parsed - The link's parts, from {@link readWikilink}.
+ * @property {object} [finding] - For `unresolved`, what is wrong: a `reason`
+ *   from {@link LINK_FINDING_REASONS}, the `target` the message names, and the
+ *   fields that reason carries.
+ */
+
+/**
+ * How an **unresolved** link renders on a page, in Foundry and on the web.
  *
  * The author's text is kept, so the sentence still reads — dropping it would
  * silently rewrite the prose. It is marked so a reader can tell that something
  * was meant to be a link, and a maintainer can find it: the appearance lives in
- * `scss/components/_unresolved-link.scss`, not here.
+ * `scss/components/_unresolved-link.scss` and in the site theme, not here.
+ *
+ * The web page renders raw HTML, so escaping is obligatory: this is the one
+ * path where *authored* text becomes markup rather than content.
  *
  * @param {string} text - The text to show, from the link's label or target.
  * @param {string} target - The address that resolved nowhere, for the tooltip.
- * @returns {string} An HTML span. The markdown renderer passes raw HTML through.
+ * @returns {string} An HTML span. The markdown renderers pass raw HTML through.
  */
 function unresolvedLink(text, target) {
     const esc = (v) =>
@@ -336,7 +390,7 @@ function unresolvedLink(text, target) {
 }
 
 /**
- * How a link to a **draft** note renders.
+ * How a link to a **draft** note renders, in Foundry and on the web.
  *
  * A note tagged `draft` exists so a link into it is not dead, and nothing more.
  * Unmarked, a reader follows a promising link into an empty page and an author
@@ -345,19 +399,14 @@ function unresolvedLink(text, target) {
  * **The wrapper carries the cue and nothing else.** The link itself is
  * untouched — Foundry enriches inside HTML, so the `@UUID` still becomes a live
  * content link, and the note is in the packs, the manifest and the index
- * exactly as any other.
- *
- * The appearance lives in `scss/components/_draft-link.scss`, beside the
- * unresolved-link partial, not here.
+ * exactly as any other. The appearance lives in
+ * `scss/components/_draft-link.scss` and in the site theme, not here.
  *
- * **Byte-identical with the site build's copy** in `web-wikilinks.mjs`, down to
- * the class name and the `title` wording — one authored link renders on two
- * surfaces, and the two builds have drifted before over exactly this kind of
- * detail. The argument is already-built markup and is deliberately not
- * escaped; the *authored* text inside it was escaped, or made into a link, by
- * whichever resolver called this.
+ * The argument is already-built markup and is deliberately not escaped; the
+ * *authored* text inside it was escaped, or made into a link, by the writer
+ * that called this.
  *
- * @param {string} inner - The resolved link, as that build emits it.
+ * @param {string} inner - The resolved link, as the target writes it.
  * @returns {string} An inline HTML span wrapping it.
  */
 function draftLink(inner) {
@@ -365,19 +414,397 @@ function draftLink(inner) {
 }
 
 /**
- * Rewrites every wikilink in a markdown body as a Foundry UUID enricher.
+ * How each target writes a {@link ResolvedLink}.
  *
- * A link that cannot be resolved is left exactly as it was and reported in
- * `unresolved`, so a content gap degrades to visible literal text rather than
- * a broken link or a failed build.
+ * | | `foundry` | `web` | `book` |
+ * | --- | --- | --- | --- |
+ * | a link | `@UUID[…]{text}`, a content link that survives import into a world | `[text](url)`, the page's relative URL | `[text](url)`, which the book sets as a cross-reference to the entry it prints, or as the page's address where it prints none |
+ * | a draft target | the link in a `sohl-draft-link` span | the same span | the link, then `(draft)` |
+ * | nothing to open | the text | the text, marked when the target is a draft | the text, then `(draft)` when the target is one |
+ * | unresolved | the text in a `sohl-unresolved-link` span | the same span | the text, then `(unresolved link)` |
+ *
+ * A link to a GM-only note, or to a secret section, is concealed by
+ * {@link presentWikilink} on every target alike.
+ *
+ * Foundry does not mark a link to a note another package publishes as a
+ * draft: its `@UUID` names the document the dependency installed, and the
+ * dependency's journal is what the reader opens.
+ *
+ * @type {Readonly<Record<"foundry"|"web"|"book", (link: ResolvedLink) => string>>}
+ */
+export const LINK_WRITERS = Object.freeze({
+    foundry(link) {
+        if (link.kind === "unresolved") return unresolvedLink(link.text, link.finding.target);
+        if (link.kind === "text") return presentWikilink(link.text, link.parsed, link.destination);
+        const reference = `@UUID[${link.uuid}]{${link.text}}`;
+        return presentWikilink(
+            link.draft ? draftLink(reference) : reference,
+            link.parsed,
+            link.destination,
+        );
+    },
+    web(link) {
+        if (link.kind === "unresolved") return unresolvedLink(link.text, link.finding.target);
+        const reference = link.kind === "link" ? `[${link.text}](${link.href})` : link.text;
+        return presentWikilink(
+            link.draft ? draftLink(reference) : reference,
+            link.parsed,
+            link.destination,
+        );
+    },
+    book(link) {
+        if (link.kind === "unresolved") return `${link.text} (unresolved link)`;
+        const reference = link.kind === "link" ? `[${link.text}](${link.href})` : link.text;
+        return presentWikilink(
+            link.draft ? `${reference} (draft)` : reference,
+            link.parsed,
+            link.destination,
+        );
+    },
+});
+
+/**
+ * What one index answers a link with: the half of resolution that depends on
+ * which index is read. A pack compile reads {@link buildWikilinkIndex}'s
+ * index and answers with UUIDs ({@link packLinkView}); the website and the
+ * book read the site index and answer with URLs ({@link siteLinkView}).
+ * Everything else — the syntax, the label rule, which failure is which, and
+ * the order the checks run in — is {@link resolveWikilinks}'s, once.
+ *
+ * @typedef {object} LinkView
+ * @property {object} context - The Address context a target is read in:
+ *   `{package, system, types, packages, noIndexPackages}`.
+ * @property {(markdown: string) => object} self - The page the link is written
+ *   on, as a destination.
+ * @property {(read: object, target: string) => ({destination: object,
+ *   itemDoc?: boolean, foreign?: boolean}|{ambiguous: true, packages?:
+ *   string[]}|undefined)} find - What an address names: a destination, which
+ *   may be an item's readable note or another package's note; a claim by more
+ *   than one package; or nothing.
+ * @property {(read: object, target: string) => boolean} collides - Whether a
+ *   target that is not an address is a short address two packages claim.
+ * @property {(read: object) => boolean} declared - Whether a lowercase
+ *   spelling of the shortcode names a note.
+ * @property {(destination: object, anchor: string, how: {samePage: boolean,
+ *   itemDoc?: boolean, foreign?: boolean}) => {reason?: string, uuid?: string, href?: string,
+ *   draft?: boolean}} locate - Where a destination opens: a finding reason
+ *   when the anchor does not belong to it, the UUID or URL it opens, or
+ *   neither when there is nothing to open.
+ */
+
+/**
+ * The reasons a target can fail to parse for, as a finding names them. A
+ * reason the address grammar gives that the finding vocabulary has no entry
+ * for means the target is not an address.
+ *
+ * @param {string|undefined} reason - The address grammar's reason.
+ * @returns {string} A reason from {@link LINK_FINDING_REASONS}.
+ */
+function parseFailure(reason) {
+    return (
+            reason &&
+                reason !== "unresolved" &&
+                reason !== "ambiguous" &&
+                LINK_FINDING_REASONS.has(reason)
+        ) ?
+            reason
+        :   "not-an-address";
+}
+
+/**
+ * Resolve one authored wikilink against a view of an index.
+ *
+ * @param {string} literal - The whole link, as authored.
+ * @param {string} rawInner - Its interior.
+ * @param {LinkView} view - The index's answers.
+ * @param {object} opts
+ * @param {string} opts.markdown - The text the link sits in.
+ * @param {Map<string, string>} [opts.captionLabels] - Numbered caption labels
+ *   by anchor, which an empty-labelled link to a figure on its own page shows.
+ * @returns {ResolvedLink} The resolution.
+ */
+function resolveWikilink(literal, rawInner, view, { markdown, captionLabels }) {
+    const parsed = readWikilink(rawInner, view.context, literal);
+    const target = parsed.rawTarget;
+    const anchor = parsed.anchor || "";
+    // An empty label is not a label: `[[x|]]` addresses the target and shows
+    // its name. One reading, from {@link authoredLabel}.
+    const label = authoredLabel(parsed);
+    const samePage = isSamePage({ target, anchor });
+    const read = samePage ? null : (parsed.problem ?? parsed.target);
+    const base = {
+        literal,
+        target,
+        anchor,
+        samePage,
+        address: read && !read.reason ? renderAddress(read) : undefined,
+        parsed,
+        draft: false,
+    };
+    const unresolved = (finding, text) => ({
+        ...base,
+        kind: "unresolved",
+        text,
+        finding: { target, ...finding },
+    });
+
+    if (parsed.attributes?.problems.length)
+        return unresolved(
+            { reason: "invalid-attributes", problems: parsed.attributes.problems },
+            label ?? target,
+        );
+
+    // **Every link carries a label**. Without one there is nothing to resolve
+    // against, and nothing to show either, a shortcode being an address rather
+    // than prose. Reported before the same-page form, because the rule is
+    // about how the link is *written*: `[[#slug]]` needs the pipe exactly as
+    // `[[skill-clmb]]` does.
+    if (!parsed.labelled)
+        return unresolved({ target: parsed.inner, reason: "unlabelled" }, parsed.inner);
+
+    let found;
+    if (samePage) {
+        found = { destination: view.self(markdown) };
+    } else {
+        // A target that does not parse as an address is a defect: there is no
+        // second namespace left to fall through to.
+        if (!read || read.reason) {
+            if (view.collides(read, target))
+                return unresolved({ reason: "ambiguous" }, label ?? target);
+            // A capital in the shortcode is refused, never lowercased. The
+            // lowercase spelling is looked up only to name it in the finding.
+            if (read?.reason === "shortcode-not-lowercase")
+                return unresolved(
+                    {
+                        reason: "shortcode-not-lowercase",
+                        shortcode: read.shortcode,
+                        ...(view.declared(read.lowercase) ?
+                            { declared: read.lowercase.shortcode }
+                        :   {}),
+                    },
+                    label ?? target,
+                );
+            return unresolved({ reason: parseFailure(read?.reason) }, label ?? target);
+        }
+        found = view.find(read, target);
+        // Two packages publish the short address, so it names neither. Its own
+        // class: the fix is the package-qualified form, not a corrected
+        // shortcode.
+        if (found?.ambiguous)
+            return unresolved(
+                {
+                    reason: "ambiguous",
+                    ...(found.packages ? { packages: found.packages } : {}),
+                },
+                label ?? target,
+            );
+        // An address that resolves nowhere is a typo or an undeclared
+        // dependency: every package it could name is either built here or
+        // fetched, so there is no third possibility left.
+        if (!found) return unresolved({ reason: "unresolved" }, label ?? target);
+    }
+
+    const { destination, itemDoc, foreign } = found;
+    // An address with an *empty* label has no prose to show, a shortcode not
+    // being display text, so the target's **current** name stands in and a
+    // rename shows at every citation with no link edited. A link to a
+    // captioned item on its own page shows the item's number.
+    const named =
+        samePage ?
+            (captionLabels?.get(anchor) ?? destination.name ?? anchor)
+        :   (destination.name ?? target);
+    const located = view.locate(destination, anchor, { samePage, itemDoc, foreign });
+    if (located.reason)
+        return unresolved(
+            { reason: located.reason, anchor },
+            label ?? (samePage ? anchor : (destination.name ?? target)),
+        );
+    const text = label ?? named;
+    const opens = located.uuid ?? located.href;
+    return {
+        ...base,
+        kind: opens === undefined ? "text" : "link",
+        text,
+        ...(located.uuid !== undefined ? { uuid: located.uuid } : {}),
+        ...(located.href !== undefined ? { href: located.href } : {}),
+        // A link into a note that exists but is not written renders marked.
+        // Presentation only — the address is unchanged — and a link to a
+        // section of its own page is not marked, because the reader is already
+        // in the note it would be telling them about.
+        draft: !samePage && Boolean(located.draft),
+        destination,
+    };
+}
+
+/**
+ * Resolve every wikilink in a markdown body, and write each in one target's
+ * form.
+ *
+ * The one link resolver. The two indexes a link is read against differ, and
+ * only that differs, so the index is a {@link LinkView} and the target a
+ * writer: {@link convertWikilinks} and {@link resolveWebWikilinks} are this,
+ * with their own view and writer.
  *
  * **Code is verbatim.** A `[[…]]` inside a fenced or indented code block, or
  * inside an inline code span, is source text an author wrote to be read as
- * written, so it is left alone and not reported. Without that, a
- * script sample containing `grid[[0]]` became a link — and only for some
- * array shapes, `[[1,2],[3,4]]` having an inner `]` the pattern cannot cross,
- * so the corruption looked arbitrary. It reaches the reader through the
- * *documented* copy of a macro while the executable copy stays correct.
+ * written, so it is left alone and not reported. Without that, a script sample
+ * containing `grid[[0]]` would become a link — and only for some array shapes,
+ * `[[1,2],[3,4]]` having an inner `]` the pattern cannot cross.
+ *
+ * **Every failure is a finding**, classified into the vocabulary
+ * {@link LINK_FINDING_REASONS} names for every reader of a link. A finding
+ * keeps the link's `offset` in `markdown` and its `occurrence` — the how-many-th
+ * finding on that literal — so a caller can report the line and column it sits
+ * on by either.
+ *
+ * @param {string} markdown - The body.
+ * @param {object} opts
+ * @param {LinkView} opts.view - The index the links resolve against.
+ * @param {(link: ResolvedLink) => string} opts.write - The target's writer,
+ *   from {@link LINK_WRITERS}.
+ * @param {Map<string, string>} [opts.captionLabels] - Numbered caption labels.
+ * @returns {{markdown: string, links: ResolvedLink[], findings: Array<{link:
+ *   string, offset: number, occurrence: number, target: string, reason:
+ *   string}>, resolved: object[]}} The written body; every link in body order;
+ *   the findings; and every destination a link outside its own page resolved
+ *   to, in body order, repeats included — the page's edges.
+ */
+export function resolveWikilinks(markdown, { view, write, captionLabels }) {
+    const links = [];
+    const findings = [];
+    const resolved = [];
+    const seen = new Map();
+    const source = String(markdown ?? "");
+    // `offset` is the third replacer argument because the pattern has exactly
+    // one capture group. It is what makes two identical links on one note
+    // tellable apart, and a position reportable at all.
+    const out = replaceOutsideCode(source, WIKILINK, (literal, rawInner, offset) => {
+        const link = resolveWikilink(literal, rawInner, view, { markdown: source, captionLabels });
+        links.push(link);
+        if (link.finding) {
+            const occurrence = (seen.get(literal) ?? 0) + 1;
+            seen.set(literal, occurrence);
+            findings.push({ link: literal, offset, occurrence, ...link.finding });
+        } else if (!link.samePage) resolved.push(link.destination);
+        return write(link);
+    });
+    return { markdown: out, links, findings, resolved };
+}
+
+/**
+ * The pack compile's view of a link: {@link buildWikilinkIndex}'s index,
+ * answered with compendium UUIDs.
+ *
+ * `[[type-shortcode|Text]]` defaults to the readable `note` Address. A stated
+ * game system names an Actor or Item; `none` names a systemless document.
+ * `doc<type>` names the readable note of an item. A journal link may carry a
+ * heading anchor, which addresses the journal's page for it; an Actor, Item or
+ * Macro link opens a sheet, which has no sections, so its anchor addresses
+ * nothing and is dropped.
+ *
+ * @param {object} index - From {@link buildWikilinkIndex}.
+ * @param {object} source - The note the links are written on.
+ * @param {string} source.type - Its type.
+ * @param {string} source.id - Its document id.
+ * @param {string} [source.pack] - The pack its own document lands in.
+ * @param {string} [source.docPack] - The pack its documentation entry lands in.
+ * @returns {LinkView} The view.
+ */
+export function packLinkView(index, { type, id, pack, docPack }) {
+    return {
+        context: {
+            package: index.contentPackage,
+            system: NOTE_SYSTEM,
+            types: index.types,
+            packages: index.packages,
+            noIndexPackages: index.noIndexPackages,
+        },
+        // The one target with no index entry of its own may be the note
+        // itself, so its own type, id and packs stand in for one.
+        self: () => index.byId?.get(`${type}/${id}`) ?? { type, id, pack, docPack },
+        find(read) {
+            // Ordinary wikilinks default to readable note content.
+            const baseType = resolveItemDocType(read.type, index.types);
+            const address = completeAddress(read, {
+                package: index.contentPackage,
+                system: NOTE_SYSTEM,
+            });
+            const itemDoc = address.system === NOTE_SYSTEM && hasDocEntry(baseType ?? read.type);
+            const local =
+                read.package === index.contentPackage ?
+                    index.byShortcode.get(`${baseType ?? read.type}/${read.shortcode}`)
+                :   undefined;
+            if (local) return { destination: local, itemDoc };
+            // Nothing local answers. A foreign package may publish this
+            // address, in which case its manifest hands back a complete UUID —
+            // including, for a section link, the anchor's own.
+            const hits = foreignHits(index, read);
+            if (hits.length > 1)
+                return { ambiguous: true, packages: hits.map((h) => h.package).filter(Boolean) };
+            return hits.length ? { destination: hits[0], foreign: true } : undefined;
+        },
+        collides: () => false,
+        declared: (read) =>
+            Boolean(shortcodeCase(index, { shortcode: "", lowercase: read }).declared),
+        locate(doc, anchor, { itemDoc = false, foreign = false } = {}) {
+            if (foreign) {
+                if (anchor && isEventAnchor(doc, anchor)) return { reason: "event-anchor" };
+                const uuid = anchor ? doc.anchors?.[anchor] : doc.uuid;
+                return uuid ? { uuid } : { reason: "unknown-anchor" };
+            }
+            // Both addresses were computed when the target was indexed. An
+            // item's readable note lives in the journals pack under its own
+            // derived entry id, and its pages hash against *that* id.
+            const addresses = index.uuidByDoc.get(doc) ?? {
+                uuid: compendiumUuid(index.packageId, doc.type, doc.id, doc.pack),
+                docUuid: compendiumUuid(
+                    index.packageId,
+                    "doc",
+                    itemDocEntryId(doc.id),
+                    doc.docPack,
+                ),
+            };
+            const entryUuid = itemDoc ? addresses.docUuid : addresses.uuid;
+            // The target has no single Foundry document. Its address is real,
+            // but a compendium has nothing to open, so the reader gets the
+            // label.
+            if (entryUuid === undefined) return {};
+            const entryId = itemDoc ? itemDocEntryId(doc.id) : doc.id;
+            const isJournal = itemDoc || packForType(doc.type).docType === "JournalEntry";
+            const anchorUuids = itemDoc ? addresses.docAnchors : addresses.anchors;
+            // A wikilink names a prose anchor; an event's id is refused here,
+            // before any surface renders a link to it.
+            if (anchor && isEventAnchor(doc, anchor)) return { reason: "event-anchor" };
+            // A `#section` the target declares no heading for. Checked here
+            // because this is the build that *emits* the link:
+            // `anchorPageId` hashes any slug into a page id, so an undeclared
+            // one compiles to a `@UUID` that dead-ends for the reader.
+            if (
+                anchor &&
+                isJournal &&
+                ((doc.anchors && !doc.anchors.has(anchor)) ||
+                    (anchorUuids && !Object.hasOwn(anchorUuids, anchor)))
+            )
+                return { reason: "unknown-anchor" };
+            return {
+                uuid:
+                    anchor && isJournal ?
+                        (anchorUuids?.[anchor] ??
+                        pageUuid(entryUuid, anchorPageId(entryId, anchor)))
+                    :   entryUuid,
+                draft: Boolean(doc.draft),
+            };
+        },
+    };
+}
+
+/**
+ * Rewrites every wikilink in a markdown body as a Foundry UUID enricher — see
+ * {@link resolveWikilinks}, with the pack compile's {@link packLinkView} and
+ * the `foundry` {@link LINK_WRITERS} entry.
+ *
+ * A link that cannot be resolved renders marked and is reported in
+ * `unresolved`.
  *
  * @param {string} markdown - The note body (frontmatter already stripped).
  * @param {object} ctx
@@ -392,250 +819,25 @@ function draftLink(inner) {
  * @param {{byShortcode: Map, types: Set}} ctx.index - From
  *   {@link buildWikilinkIndex}.
  * @param {Map<string, string>} [ctx.captionLabels] - Numbered caption references.
- * @returns {{markdown: string, unresolved: Array<{link: string, target: string,
- *   offset: number, reason: string, packages?: string[], anchor?: string}>}}
- *   Each `reason` is one of {@link LINK_FINDING_REASONS}, the vocabulary all
- *   three resolvers share — `ambiguous` carries the claiming `packages`
+ * @returns {{markdown: string, links: ResolvedLink[], unresolved: Array<{link:
+ *   string, target: string, offset: number, reason: string, packages?:
+ *   string[], anchor?: string}>}} Each `reason` is one of
+ *   {@link LINK_FINDING_REASONS} — `ambiguous` carries the claiming `packages`
  *   and `unknown-anchor` the section it named. `offset` is the link's 0-based
  *   position in `markdown`, which is what lets a caller report the line and
  *   column it sits on.
  */
 export function convertWikilinks(markdown, { type, id, pack, docPack, index, captionLabels }) {
-    const unresolved = [];
-
-    // `offset` is the third replacer argument because the pattern has exactly
-    // one capture group. It is what makes two identical unresolved links on
-    // one note tellable apart, and a position reportable at all.
-    const out = replaceOutsideCode(markdown, WIKILINK, (all, rawInner, offset) => {
-        const parsed = readWikilink(
-            rawInner,
-            {
-                package: index.contentPackage,
-                system: "note",
-                types: index.types,
-                packages: index.packages,
-                noIndexPackages: index.noIndexPackages,
-            },
-            all,
-        );
-        const target = parsed.rawTarget;
-        const slug = parsed.anchor || null;
-        if (parsed.attributes?.problems.length) {
-            unresolved.push({
-                link: all,
-                target,
-                offset,
-                reason: "invalid-attributes",
-                problems: parsed.attributes.problems,
-            });
-            return unresolvedLink(authoredLabel(parsed) ?? target, target);
-        }
-
-        // **Every link carries a label**. Without one there is nothing
-        // to resolve against: a shortcode is an address rather than prose, so
-        // the link has neither a target this build can find nor text to show.
-        // Reported before anything else, including the same-page form, because
-        // it is a statement about how the link is *written* — `[[#slug]]` needs
-        // the pipe exactly as `[[skill-clmb]]` does.
-        if (!parsed.labelled) {
-            unresolved.push({
-                link: all,
-                target: target || (slug ? `#${slug}` : ""),
-                offset,
-                reason: "unlabelled",
-                addressed: false,
-            });
-            return unresolvedLink(parsed.inner, parsed.inner);
-        }
-
-        // An *empty* label is not a label — `[[x|]]` means "show the target's
-        // name" — and that reading comes from {@link authoredLabel} so the web
-        // resolver cannot draw the line somewhere else.
-        let text = authoredLabel(parsed) ?? "";
-
-        // Resolve the document: the source note itself for an empty target, or
-        // the address the target parses as.
-        let doc;
-        // Set when the qualifier was the virtual `doc<type>` form, so the UUID
-        // is built against the item doc entry rather than the item itself.
-        let itemDoc = false;
-        // Kept for the foreign fallback below, which needs the parsed address.
-        let qualifiedRead = null;
-        if (target === "" && slug) {
-            doc = index.byId?.get(`${type}/${id}`) ?? { type, id, pack, docPack };
-        } else {
-            const qualified = parsed.problem ?? parsed.target;
-            qualifiedRead = qualified;
-            // A target that does not parse as an address is a defect: there is
-            // no second namespace left to fall through to.
-            if (!qualified || qualified.reason) {
-                unresolved.push({
-                    link: all,
-                    target,
-                    offset,
-                    reason: qualified?.reason ?? "not-an-address",
-                    ...(qualified?.reason === "shortcode-not-lowercase" ?
-                        shortcodeCase(index, qualified)
-                    :   {}),
-                    addressed: true,
-                });
-                return unresolvedLink(text || target, target);
-            }
-            // Ordinary wikilinks default to readable note content.
-            const baseType = resolveItemDocType(qualified.type, index.types);
-            const address = completeAddress(qualified, {
-                package: index.contentPackage,
-                system: NOTE_SYSTEM,
-            });
-            itemDoc = address.system === NOTE_SYSTEM && hasDocEntry(baseType ?? qualified.type);
-            if (qualified.package === index.contentPackage)
-                doc = index.byShortcode.get(`${baseType ?? qualified.type}/${qualified.shortcode}`);
-        }
-        if (!doc) {
-            // Nothing local answers. A foreign package may publish this
-            // address, in which case the manifest hands back a complete UUID —
-            // including, for a section link, the anchor's own — so nothing is
-            // derived here.
-            const hits = foreignHits(index, qualifiedRead);
-            if (hits.length > 1) {
-                // Two packages publish the short address, so it names neither.
-                // Its own class: the fix is the package-qualified form, not a
-                // corrected shortcode.
-                unresolved.push({
-                    link: all,
-                    target,
-                    offset,
-                    reason: "ambiguous",
-                    packages: hits.map((h) => h.package).filter(Boolean),
-                    addressed: true,
-                });
-                return unresolvedLink(text || target, target);
-            }
-            const hit = hits[0] ?? null;
-            if (hit && slug && isEventAnchor(hit, slug)) {
-                unresolved.push({
-                    link: all,
-                    target,
-                    offset,
-                    reason: "event-anchor",
-                    anchor: slug,
-                    addressed: true,
-                });
-                return unresolvedLink(text || target, target);
-            }
-            if (hit) {
-                const uuid = slug ? hit.anchors?.[slug] : hit.uuid;
-                if (uuid) {
-                    return presentWikilink(
-                        `@UUID[${uuid}]{${text || hit.name || target}}`,
-                        parsed,
-                        hit,
-                    );
-                }
-                unresolved.push({
-                    link: all,
-                    target,
-                    offset,
-                    reason: "unknown-anchor",
-                    anchor: slug,
-                    addressed: true,
-                });
-                return unresolvedLink(text || target, target);
-            }
-            unresolved.push({
-                link: all,
-                target,
-                offset,
-                reason: "unresolved",
-                // An address that resolves nowhere is a typo: every package it
-                // could name is either built here or vendored, so there is no
-                // third possibility left.
-                addressed: true,
-            });
-            return unresolvedLink(text || target, target);
-        }
-
-        // An address with an *empty* label — `[[skill-clmb|]]` — has no prose
-        // to show, a shortcode being an address rather than display text, so
-        // the document's **current** name stands in and a rename shows at every
-        // citation with no link edited. The knowledgebase build reads
-        // the same authored link the same way.
-        if (!text)
-            text = (target === "" && slug ? captionLabels?.get(slug) : null) ?? doc.name ?? target;
-
-        // Both addresses were computed when the target was indexed. An item
-        // doc lives in the journals pack under its own derived entry id, and
-        // its pages hash against *that* id — not the item's.
-        //
-        // The one target with no index entry is the note itself: a `[[#slug]]`
-        // self-link is resolved from the source's own type and id, which the
-        // caller supplied, so it is addressed the same way here.
-        const addresses = index.uuidByDoc.get(doc) ?? {
-            uuid: compendiumUuid(index.packageId, doc.type, doc.id, doc.pack),
-            docUuid: compendiumUuid(index.packageId, "doc", itemDocEntryId(doc.id), doc.docPack),
-        };
-        const entryUuid = itemDoc ? addresses.docUuid : addresses.uuid;
-        // The target has no single Foundry document. Its address is real, but
-        // a compendium has nothing to open, so the reader gets the label.
-        if (entryUuid === undefined) return presentWikilink(text, parsed, doc);
-        const entryId = itemDoc ? itemDocEntryId(doc.id) : doc.id;
-        const isJournal = itemDoc || packForType(doc.type).docType === "JournalEntry";
-        // A JournalEntry link opens a journal — at its first page, or at the
-        // page an anchor names. An Item or Actor link opens that document's
-        // *sheet*, which has no sections, so the anchor has nothing to address
-        // and is dropped. Forging a JournalEntryPage id onto a document that
-        // can never hold one is what made such links dead-end; an
-        // an item's pages are addressed through its `note` Address.
-        // A `#section` the target declares no heading for. Checked here, and
-        // not only by `package-build links`, because this is the build that
-        // *emits* the link: `anchorPageId` will hash any slug into a page id,
-        // so an undeclared one compiles to a `@UUID` that dead-ends for the
-        // reader. A foreign anchor has always been checked this way —
-        // the manifest carries the map — and a local one now is too, from the
-        // anchor set the index carries.
-        const anchorUuids = itemDoc ? addresses.docAnchors : addresses.anchors;
-        // A wikilink names a prose anchor; an event's id is refused here, before
-        // any surface renders a link to it.
-        if (slug && isEventAnchor(doc, slug)) {
-            unresolved.push({
-                link: all,
-                target,
-                offset,
-                reason: "event-anchor",
-                anchor: slug,
-                addressed: true,
-            });
-            return unresolvedLink(text || doc.name || target, target);
-        }
-        if (
-            slug &&
-            isJournal &&
-            ((doc.anchors && !doc.anchors.has(slug)) ||
-                (anchorUuids && !Object.hasOwn(anchorUuids, slug)))
-        ) {
-            unresolved.push({
-                link: all,
-                target,
-                offset,
-                reason: "unknown-anchor",
-                anchor: slug,
-                addressed: true,
-            });
-            return unresolvedLink(text || doc.name || target, target);
-        }
-        const uuid =
-            slug && isJournal ?
-                (anchorUuids?.[slug] ?? pageUuid(entryUuid, anchorPageId(entryId, slug)))
-            :   entryUuid;
-        const link = `@UUID[${uuid}]{${text}}`;
-        // A link into a note that exists but is not written renders marked.
-        // Presentation only — the UUID above is unchanged, and a
-        // `[[#slug]]` self-link is not marked because the reader is already in
-        // the note it would be telling them about.
-        return presentWikilink(doc.draft ? draftLink(link) : link, parsed, doc);
+    const result = resolveWikilinks(markdown, {
+        view: packLinkView(index, { type, id, pack, docPack }),
+        write: LINK_WRITERS.foundry,
+        captionLabels,
     });
-
-    return { markdown: out, unresolved };
+    return {
+        markdown: result.markdown,
+        links: result.links,
+        unresolved: result.findings.map(({ occurrence, ...finding }) => finding),
+    };
 }
 
 /**
@@ -714,3 +916,280 @@ export function resolveReference(index, ref, hint) {
     }
     return undefined;
 }
+
+/**
+ * Whether a page's declared anchors include the slug a link names.
+ *
+ * A local page carries a `Set` built by {@link module:engine/site-index}.
+ * A foreign page declares prose anchors in its note metadata, independently
+ * of whether it has a Foundry target map. An empty collection declares none.
+ * An absent collection leaves the target unchecked.
+ *
+ * @param {Set<string>|Record<string, string>|Array<{slug: string, kind: string}>|undefined} anchors - The page's
+ *   declared anchors, or `undefined` where none were recorded.
+ * @param {string} slug - The anchor a link names.
+ * @returns {boolean} Whether the anchor is declared, or `true` when `anchors`
+ *   is `undefined` — which reads as "nothing to check against" rather than
+ *   "declares none".
+ */
+function hasAnchor(anchors, slug) {
+    if (!anchors) return true;
+    if (Array.isArray(anchors))
+        return anchors.some((anchor) => anchor.kind === "prose" && anchor.slug === slug);
+    return anchors instanceof Set ? anchors.has(slug) : Object.hasOwn(anchors, slug);
+}
+
+/**
+ * The site index entry an address names, or `undefined`.
+ *
+ * Every omitted segment defaults from where the link is written — the package
+ * from the citing package, the system from the block, which on a page body is
+ * `note` — so the target expands to exactly one canonical address and this is
+ * a plain lookup: one key names one entry.
+ *
+ * A local target may also be keyed by its short form. On the web that is not a
+ * second answer: an item note renders as **one page** which is its own
+ * documentation, so `skill/climb`, `docskill/climb` and both canonical
+ * addresses are all the same value.
+ *
+ * @param {Map<string, object>} index - The page index to look in.
+ * @param {object|null} read - The parsed target.
+ * @param {string} contentPackage - The citing package, which an omitted package
+ *   segment defaults from.
+ * @returns {object|undefined} The indexed page, or `undefined` when the target
+ *   is not an address or nothing publishes it.
+ */
+function lookupRead(index, read, contentPackage) {
+    if (!read || read.reason) return undefined;
+    const key = expandAddress(read, { package: contentPackage, system: NOTE_SYSTEM });
+    const found = index.get(key);
+    if (found || read.package) return found;
+    return (
+        index.get(`${read.itemDoc ? "doc" : ""}${read.type}/${read.shortcode}`.toLowerCase()) ??
+        undefined
+    );
+}
+
+/**
+ * The website's and the book's view of a link: the site index, answered with
+ * URLs.
+ *
+ * The site index is keyed case-insensitively by the canonical
+ * `package-system-type-shortcode` address, by `type/shortcode` and by the
+ * site's own `section/slug`; a fully qualified address another package
+ * publishes is looked up in its fetched index. Local wins: a live build is
+ * authoritative and a fetched index can only be staler. A short address two
+ * packages claim is in the index's `ambiguous` set, and is a finding of its
+ * own.
+ *
+ * A target that **resolved** to an entry with no page is not unresolved: a
+ * pack-only package publishes Foundry addresses and no web pages, so the
+ * author wrote a real address and there is simply nothing to link to.
+ *
+ * @param {object} ctx - What {@link module:engine/site-index.wikiContext}
+ *   returns, with the page's own `anchors` and `eventAnchors`.
+ * @param {string} body - The page's text, which a link to its own section is
+ *   concealed by when the section is secret.
+ * @returns {LinkView} The view.
+ */
+export function siteLinkView(ctx, body) {
+    let ownAnchors = ctx.noteAnchors;
+    // The bucket an ambiguity is recorded under is the *short* address — the
+    // only form two packages can collide on, since a qualified one names its
+    // package.
+    const collideKey = (read, target) =>
+        read && !read.reason && read.package === ctx.contentPackage ?
+            `${read.type}/${read.shortcode}`.toLowerCase()
+        :   target.toLowerCase();
+    const lookup = (read) =>
+        lookupRead(ctx.index, read, ctx.contentPackage) ??
+        // A short form names *this* package, so it never reaches a fetched
+        // index; only a fully qualified address does.
+        (ctx.foreign && read?.package ?
+            lookupRead(ctx.foreign, read, ctx.contentPackage)
+        :   undefined);
+    return {
+        context: {
+            package: ctx.contentPackage,
+            system: NOTE_SYSTEM,
+            types: ctx.contentTypes ?? new Set(),
+            packages: ctx.packages,
+            noIndexPackages: ctx.noIndexPackages,
+        },
+        self: () => ({ noteAnchors: (ownAnchors ??= collectAnchors(body)) }),
+        find(read, target) {
+            const hit = lookup(read);
+            if (hit) return { destination: hit };
+            return ctx.collide?.has(collideKey(read, target)) ? { ambiguous: true } : undefined;
+        },
+        collides: (read, target) => Boolean(ctx.collide?.has(collideKey(read, target))),
+        declared: (read) => Boolean(lookup(read)),
+        locate(hit, anchor, { samePage }) {
+            // Checked against this page's own anchors, exactly as a link into
+            // another page is: a self-link naming a section the page does not
+            // declare is as dead as one naming a section nowhere does.
+            if (samePage) {
+                if (isEventAnchor(ctx, anchor)) return { reason: "event-anchor" };
+                if (!hasAnchor(ctx.anchors, anchor)) return { reason: "unknown-anchor" };
+                return { href: `#${slugify(anchor)}` };
+            }
+            if (anchor && isEventAnchor(hit, anchor)) return { reason: "event-anchor" };
+            // A `#section` the target declares no heading for joins onto the
+            // URL unchecked otherwise, and dead-ends for the reader.
+            if (anchor && !hasAnchor(hit.noteAnchors ?? hit.anchors, anchor))
+                return { reason: "unknown-anchor" };
+            // A pack-only package's entries carry no URL: the reader gets the
+            // text and no href, rather than `[Name](undefined)`.
+            return {
+                ...(hit.url ? { href: anchor ? `${hit.url}#${slugify(anchor)}` : hit.url } : {}),
+                draft: Boolean(hit.draft),
+            };
+        },
+    };
+}
+
+/**
+ * A wikilink, as it is written, anywhere in a value that is not markdown.
+ *
+ * Deliberately its own pattern rather than the body resolver's: nothing here is
+ * markdown, so there is no fence or code span to step around, and a frontmatter
+ * value is a single line by construction.
+ */
+// The same syntax the body scan reads — see `./wikilink-syntax.mjs`.
+const FRONTMATTER_WIKILINK = new RegExp(WIKILINK.source, "g");
+
+/**
+ * Every wikilink authored inside a frontmatter value.
+ *
+ * Wikilinks are resolved in a note's **body**. Frontmatter is not markdown and
+ * is never walked by the resolver, so a link written in one would be copied
+ * through verbatim and reach the reader as literal `[[…]]` text, in whatever the
+ * theme renders that field as (an infobox row, a description, a card
+ * subtitle). Nothing downstream notices: the value is a valid string, the page
+ * builds, and the defect is visible only to someone who looks at it.
+ *
+ * So the form is refused rather than resolved. Resolving it would mean choosing
+ * an output syntax for a field whose renderer is unknown to this build — a
+ * markdown link is inert in a template that prints the value as text, and an
+ * `<a>` is unusable in one that escapes it — and would quietly bless an
+ * authoring habit that the pack build has no way to honour at all. Frontmatter
+ * carries data; a link belongs in prose.
+ *
+ * Values are read from the *parsed* frontmatter, so a `[[` inside a YAML comment
+ * is not a hit, and every hit can be named by the path a reader would look at.
+ *
+ * @param {unknown} fm - Parsed frontmatter, as `readMatter` returns it.
+ * @returns {Array<{path: string, link: string}>} In reading order; `path` is the
+ *   dotted key path of the offending value (`government.summary`, `aliases.1`).
+ */
+export function frontmatterWikilinks(fm) {
+    const hits = [];
+    const visit = (value, trail) => {
+        if (typeof value === "string") {
+            for (const m of value.matchAll(FRONTMATTER_WIKILINK)) {
+                hits.push({ path: trail, link: m[0] });
+            }
+        } else if (Array.isArray(value)) {
+            value.forEach((v, i) => visit(v, `${trail}.${i}`));
+        } else if (isPlainMap(value)) {
+            for (const [k, v] of Object.entries(value)) {
+                visit(v, trail ? `${trail}.${k}` : k);
+            }
+        }
+    };
+    if (!isPlainMap(fm)) return hits;
+    visit(fm, "");
+    return hits;
+}
+
+/**
+ * Whether a value is a YAML mapping rather than a scalar the parser built into
+ * an object of its own (a `Date`, which is what an unquoted date becomes).
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainMap(value) {
+    return (
+        typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Date)
+    );
+}
+
+/**
+ * Rewrites the embeds and wikilinks in a markdown body for the website or the
+ * book — see {@link resolveWikilinks}, with {@link siteLinkView} and the `web`
+ * or `book` {@link LINK_WRITERS} entry.
+ *
+ *   `[[type-shortcode|Text]]`       → `[Text](/section/slug/)`
+ *   `[[type-shortcode|]]`           → the same, showing the target's own name
+ *   `[[type-shortcode#slug|Text]]`  → `[Text](/section/slug/#slug)`
+ *   `[[#slug|Text]]`                → `[Text](#slug)`
+ *
+ * **Every target that resolves nowhere fails the build.** Failures are
+ * collected in `ctx.errors`, each carrying the authored `link` and its
+ * `occurrence` so a caller can report the line and column it sits on. The
+ * link still renders, marked: the mark is for whoever reads the page, the
+ * failure for its author.
+ *
+ * ## Embeds first, and they are not links
+ *
+ * `![[address|label]]` names a file rather than a note, so it is resolved into
+ * an ordinary markdown image before anything looks for a link — which is what
+ * stops the link pass reading an embed's interior as a link to a note nobody
+ * wrote. The image the rewrite leaves behind is what
+ * {@link module:engine/content-images.renderImageFigures} turns into a figure
+ * for the website, and what the book reads its staging list out of.
+ *
+ * ## Every hit is recorded, so the page's edges come out of one pass
+ *
+ * A caller that hands in `ctx.resolved` is given every index entry a link on
+ * the page resolved to, in body order, repeats included. Nothing is recorded
+ * for a same-page anchor or for a target that resolved nowhere.
+ *
+ * @param {string} body - The markdown body.
+ * @param {object} ctx - `{ index, assets, collide, contentTypes, packages,
+ *   noIndexPackages, foreign, errors, src, file, resolved, output, anchors,
+ *   eventAnchors, captionLabels }`, as
+ *   {@link module:engine/site-index.wikiContext} builds it. `output` is
+ *   `"book"` for the book and defaults to the website. `anchors` and
+ *   `eventAnchors` are what *this* page declares, which a `[[#slug]]`
+ *   self-link is checked against; absent, a self-link is not checked. `src`
+ *   is the page's display path and `file` the source file a diagnostic names
+ *   — absent, `src` stands in.
+ * @returns {string} The body with embeds and wikilinks rewritten.
+ */
+export function resolveWebWikilinks(body, ctx) {
+    const seen = new Map();
+    const record = (literal, finding) => {
+        const occurrence = (seen.get(literal) ?? 0) + 1;
+        seen.set(literal, occurrence);
+        ctx.errors.push({
+            file: ctx.file ?? ctx.src,
+            src: ctx.src,
+            link: literal,
+            occurrence,
+            ...finding,
+        });
+    };
+    // An embed names a file, so it resolves before anything looks for a link.
+    // Its findings are recorded rather than rendered: the rewrite already
+    // leaves an embed it cannot resolve exactly as authored.
+    const embedded = resolveEmbeds(body, { index: ctx.assets });
+    for (const u of embedded.unresolved) {
+        record(u.link, { target: u.target, reason: u.reason, ...(u.type ? { type: u.type } : {}) });
+    }
+    for (const problem of embedded.problems) {
+        record(problem.link, { target: problem.link, message: problem.message });
+    }
+    const result = resolveWikilinks(embedded.markdown, {
+        view: siteLinkView(ctx, body),
+        write: ctx.output === "book" ? LINK_WRITERS.book : LINK_WRITERS.web,
+        captionLabels: ctx.captionLabels,
+    });
+    for (const { link, offset, occurrence, ...finding } of result.findings) record(link, finding);
+    ctx.resolved?.push(...result.resolved);
+    return result.markdown;
+}