@behackl/citation-js-extras 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,6 +1,76 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import Cite from "citation-js";
+import CSL from "citeproc";
 import { MathProtector } from "./math.js";
+/**
+ * Ready-made badges for the identifiers of mathematical bibliographies. Their
+ * matchers accept the spellings found in real exports (`doi:10…`,
+ * `https://doi.org/10…`, `arXiv:2301.00001v2`, `MR1234567`). Use them as they
+ * are, or spread one to change a property:
+ *
+ * ```ts
+ * badges: [{ ...badgePresets.doi, className: "badge" }, badgePresets.arxiv]
+ * ```
+ *
+ * The title link uses the same preset for these fields, so both always agree.
+ */
+export const badgePresets = Object.freeze({
+    doi: Object.freeze({
+        field: "doi",
+        label: "DOI",
+        url: "https://doi.org/$1",
+        match: /^(?:doi:\s*|https?:\/\/(?:dx\.)?doi\.org\/)?(10\.\S+)$/i,
+    }),
+    arxiv: Object.freeze({
+        field: "arxiv",
+        label: "arXiv",
+        url: "https://arxiv.org/abs/$1",
+        match: /^(?:arxiv:\s*)?(.+?)(?:v\d+)?$/i,
+    }),
+    mrnumber: Object.freeze({
+        field: "mrnumber",
+        label: "MR",
+        url: "https://mathscinet.ams.org/mathscinet-getitem?mr=$1",
+        match: /^(?:MR\s*)?(\d+)/i,
+    }),
+    zbl: Object.freeze({
+        field: "zbl",
+        label: "zbMATH",
+        url: "https://zbmath.org/?q=an:$1",
+        match: /^(?:Zbl\s*)?(\d+\.\d+)/i,
+    }),
+});
+const DEFAULT_TITLE_LINK = ["url", "doi", "arxiv"];
+const FORMAT_DEFAULT_KEYS = [
+    "titleLink", "badges", "linkifyUrls", "itemAttributes", "badgeListClassName",
+    "printLinkedIdentifiers", "sanitize", "lang", "appendBadges", "linkAttributes",
+    "wrapVariable",
+];
+/**
+ * The render call in progress. Engines are shared between instances (creating
+ * one compiles the style, which is slow), so their callbacks look up whoever is
+ * rendering right now. Rendering is synchronous, which makes this safe.
+ */
+let current;
+/** Engines by style and locale, like citation-js's own cache. */
+const engines = new Map();
+const busy = new Set();
+function createEngine(templateName, lang) {
+    const { templates, locales } = Cite.plugins.config.get("@csl");
+    const engine = new CSL.Engine({
+        retrieveItem: (id) => {
+            const item = current?.items.get(id);
+            if (!item)
+                throw new Error(`Cannot find entry with id '${id}'`);
+            return item;
+        },
+        retrieveLocale: (locale) => locales.get(locale) ?? locales.get(locale.replace("-", "_")) ?? {},
+        variableWrapper: (params, pre, str, post) => current ? current.wrap(params, pre, str, post) : pre + str + post,
+    }, templates.get(templateName), locales.has(lang) ? lang : undefined, true);
+    // As citation-js: DOIs and URLs are linked by us, not by citeproc.
+    engine.opt.development_extensions.wrap_url_and_doi = false;
+    return engine;
+}
 // ---------------------------------------------------------------------------
 // Bibliography class
 // ---------------------------------------------------------------------------
@@ -11,18 +81,34 @@ export class Bibliography {
     entries;
     customFieldNames;
     math;
+    /** Formatting defaults from the constructor; each call may override them. */
+    formatDefaults;
+    rendering;
     constructor(options) {
         const bibData = maybeReadFile(options.data);
         this.customFieldNames = options.customFields ?? [];
+        this.formatDefaults = {};
+        for (const key of FORMAT_DEFAULT_KEYS) {
+            if (options[key] !== undefined)
+                this.formatDefaults[key] = options[key];
+        }
         // Register CSL style
         this.templateName = this.registerStyle(options.cslStyle);
         // Two-pass parse: raw (preserves all fields) + CSL (for formatting)
         const { plugins } = Cite;
         const rawEntries = plugins.input.chainLink(bibData);
         const rawMap = new Map();
+        const duplicates = new Set();
         for (const entry of rawEntries) {
+            if (rawMap.has(entry.label))
+                duplicates.add(entry.label);
             rawMap.set(entry.label, entry.properties);
         }
+        // Raw fields are merged by key, so a duplicate would silently give one
+        // entry the other's fields.
+        if (duplicates.size) {
+            throw new Error(`Duplicate citation key${duplicates.size > 1 ? "s" : ""}: ${[...duplicates].join(", ")}`);
+        }
         // Protect resolved raw fields, after BibTeX strings/concatenations are parsed
         // but before the lossy TeX-to-CSL conversion. Keep the original raw map intact.
         this.math = options.preserveMath
@@ -37,8 +123,9 @@ export class Bibliography {
             const raw = rawMap.get(key) ?? {};
             const custom = {};
             for (const f of this.customFieldNames) {
-                if (raw[f] != null)
-                    custom[f] = String(raw[f]);
+                const value = raw[f.toLowerCase()] ?? raw[f];
+                if (value != null)
+                    custom[f] = String(value);
             }
             return {
                 csl,
@@ -62,17 +149,19 @@ export class Bibliography {
         return this.entries.filter((e) => Object.entries(criteria).every(([k, v]) => e.custom[k] === v));
     }
     /**
-     * Return a sorted **copy** of the given entries.
+     * Return a sorted **copy** of the given entries. Ties keep their input order.
      *
      * @param entries - entries to sort (not mutated)
-     * @param by - `'year'` (default) or a custom field name
+     * @param by - `'year'` (default), `'date'` (year, then month, then day; a
+     *   missing part counts as 0), or a custom field name
      * @param order - `'desc'` (default) or `'asc'`
      */
     sort(entries, { by = "year", order = "desc" } = {}) {
+        const keyOf = (e) => by === "year" ? [e.year ?? 0]
+            : by === "date" ? issuedParts(e)
+                : [e.custom[by] ?? ""];
         return [...entries].sort((a, b) => {
-            const va = by === "year" ? (a.year ?? 0) : (a.custom[by] ?? "");
-            const vb = by === "year" ? (b.year ?? 0) : (b.custom[by] ?? "");
-            const cmp = va < vb ? -1 : va > vb ? 1 : 0;
+            const cmp = compareKeys(keyOf(a), keyOf(b));
             return order === "desc" ? -cmp : cmp;
         });
     }
@@ -81,14 +170,12 @@ export class Bibliography {
     // -------------------------------------------------------------------------
     /**
      * Format a single entry as an HTML string (no wrapper element).
-     * Applies title linking and badge injection.
+     * Applies title linking, badge injection and URL linkification.
      */
     formatEntry(entry, options = {}) {
-        const rendered = this.renderCslEntries([entry]);
-        const raw = rendered[0]?.[1] ?? "";
-        const innerHtml = unwrapCslEntry(raw) ?? raw.trim();
-        const decorated = this.decorateEntryHtml(entry, innerHtml, options);
-        return this.math ? this.math.restore(decorated, options.renderMath) : decorated;
+        const merged = this.mergeOptions(options);
+        const [html = ""] = this.renderItems([entry], merged);
+        return this.finish(html, merged);
     }
     /**
      * Format a list of entries as a complete HTML bibliography.
@@ -96,33 +183,117 @@ export class Bibliography {
     formatHtml(entries, options = {}) {
         if (entries.length === 0)
             return "";
-        const tag = options.list ?? "ol";
-        const attrs = options.listAttributes ?? (tag === "ol" ? { reversed: true } : {});
-        const attrStr = renderAttributes(attrs);
-        // Render all entries in one citeproc run so style-dependent numbering/state
-        // (e.g. vancouver left-margin labels) remains correct.
-        const rendered = this.renderCslEntries(entries);
-        const renderedMap = new Map(rendered.map(([id, html]) => [id, html]));
+        const merged = this.mergeOptions(options);
+        const tag = merged.list ?? "ol";
+        const listAttributes = merged.listAttributes ?? (tag === "ol" ? { reversed: true } : {});
         const itemTag = tag === "div" ? "div" : "li";
-        const items = entries.map((entry, index) => {
-            const id = String(entry.csl.id ?? entry.key);
-            const raw = renderedMap.get(id)
-                ?? renderedMap.get(entry.key)
-                ?? rendered[index]?.[1]
-                ?? "";
-            const innerRaw = unwrapCslEntry(raw) ?? raw.trim();
-            const inner = this.decorateEntryHtml(entry, innerRaw, options);
-            return `<${itemTag} data-csl-entry-id="${escapeAttr(entry.key)}" class="csl-entry">${inner}</${itemTag}>`;
+        // Rendered in one citeproc run so style-dependent numbering/state
+        // (e.g. vancouver left-margin labels) remains correct.
+        const items = this.renderItems(entries, merged).map((inner, index) => {
+            const entry = entries[index];
+            const attributes = withClass({ "data-csl-entry-id": entry.key, ...(merged.itemAttributes && attributed(entry, () => merged.itemAttributes(entry))) }, "csl-entry");
+            return `<${itemTag}${renderAttributes(attributes)}>${inner}</${itemTag}>`;
         });
-        let html = `<${tag}${attrStr} class="csl-bib-body">\n${items.join("\n")}\n</${tag}>`;
-        if (options.linkifyUrls !== false) {
-            html = linkifyBareUrls(html);
-        }
-        return this.math ? this.math.restore(html, options.renderMath) : html;
+        const list = `<${tag}${renderAttributes(withClass(listAttributes, "csl-bib-body"))}>\n${items.join("\n")}\n</${tag}>`;
+        return this.finish(list, merged);
+    }
+    /**
+     * The links an entry gets with these options: its title link and badges.
+     * The same resolution the formatted HTML uses, so the two always agree; for
+     * rendering badges yourself, pair it with `appendBadges: false`.
+     */
+    links(entry, options = {}) {
+        return this.resolveLinks(entry, this.mergeOptions(options));
     }
     // -------------------------------------------------------------------------
     // Private helpers
     // -------------------------------------------------------------------------
+    /** Per-call options win over the defaults given to the constructor. */
+    mergeOptions(options) {
+        const merged = { ...options };
+        for (const key of FORMAT_DEFAULT_KEYS) {
+            if (merged[key] === undefined)
+                merged[key] = this.formatDefaults[key];
+        }
+        return merged;
+    }
+    /**
+     * Entry HTML without wrapper, shared by `formatEntry` and `formatHtml` so
+     * both honour the same options. Links are resolved first: they decide what
+     * the style may print and what is added afterwards.
+     */
+    renderItems(entries, options) {
+        const links = entries.map(entry => this.resolveLinks(entry, options));
+        const csl = entries.map((entry, index) => displayCsl(entry.csl, options.printLinkedIdentifiers ? [] : linkedFields(links[index])));
+        const byId = new Map(entries.map((entry, index) => [String(entry.csl.id ?? entry.key), { entry, links: links[index], titleLinked: false }]));
+        this.rendering = { options, byId };
+        let rendered;
+        try {
+            rendered = this.renderCslEntries(csl, options.lang ?? "en-US");
+        }
+        finally {
+            this.rendering = undefined;
+        }
+        const renderedMap = new Map(rendered);
+        return entries.map((entry, index) => {
+            const id = String(entry.csl.id ?? entry.key);
+            const raw = renderedMap.get(id) ?? rendered[index]?.[1] ?? "";
+            let html = unwrapCslEntry(raw) ?? raw.trim();
+            return decorate(html, byId.get(id).titleLinked, links[index], options);
+        });
+    }
+    /**
+     * Called by citeproc for every variable it renders. Everything the library
+     * adds to the citation text happens here, one variable at a time, instead of
+     * by searching the finished HTML:
+     *
+     * - the title link, around the exact output of the title variable, so no
+     *   quotes, markup or capitalisation the style applies can hide the title;
+     * - bare URLs in a variable (e.g. in a `note`) become links. Formulas are
+     *   still placeholders here, so MathML's xmlns URL is never linked;
+     * - the consumer's `wrapVariable`, outermost.
+     */
+    wrapVariable(params, pre, str, post) {
+        const state = this.rendering;
+        const item = state?.byId.get(String(params.itemData?.id));
+        if (!state || !item || params.context !== "bibliography" || params.mode !== "html" || !str) {
+            return pre + str + post;
+        }
+        const variable = params.variableNames?.[0] ?? "";
+        let html = str;
+        // A style may print the title in another variable's place, e.g. APA
+        // substitutes it for missing authors; citeproc then doesn't call it `title`.
+        const isTitle = variable === "title"
+            || (typeof item.entry.csl.title === "string" && plainText(str) === plainText(item.entry.csl.title));
+        if (isTitle && item.links.title && !item.titleLinked) {
+            html = linkHtml(item.links.title, html, state.options);
+            item.titleLinked = true;
+        }
+        if (state.options.linkifyUrls !== false)
+            html = linkifyBareUrls(html);
+        const wrap = state.options.wrapVariable;
+        if (wrap)
+            html = attributed(item.entry, () => wrap(html, { variable, entry: item.entry }));
+        return pre + html + post;
+    }
+    /** Sanitize while formulas are placeholders, then insert rendered math. */
+    finish(html, options) {
+        const safe = options.sanitize ? options.sanitize(html) : html;
+        return this.math ? this.math.restore(safe, options.renderMath) : safe;
+    }
+    resolveLinks(entry, options) {
+        const badges = options.badges ?? [];
+        const rendered = [];
+        for (const badge of badges) {
+            for (const link of applyBadge(entry, badge)) {
+                rendered.push({ kind: "badge", field: badge.field, ...link, className: badge.className, entry });
+            }
+        }
+        const title = typeof entry.csl.title === "string" && entry.csl.title.trim()
+            ? resolveTitleLink(entry, options.titleLink ?? DEFAULT_TITLE_LINK, badges)
+            : undefined;
+        return title ? { title, badges: rendered } : { badges: rendered };
+    }
     registerStyle(cslStyle) {
         if (!cslStyle)
             return "apa";
@@ -141,127 +312,41 @@ export class Bibliography {
         }
         return name;
     }
-    renderCslEntries(entries) {
-        const cite = new Cite(entries.map((entry) => entry.csl));
-        const out = cite.format("bibliography", {
-            format: "html",
-            template: this.templateName,
-            lang: "en-US",
-            nosort: true,
-            asEntryArray: true,
-        });
-        if (!Array.isArray(out))
-            return [];
-        return out
-            .filter((item) => Array.isArray(item) && item.length >= 2)
-            .map(([id, html]) => [String(id), String(html)]);
-    }
-    decorateEntryHtml(entry, html, options) {
-        let out = html;
-        // Link the title text
-        const titleUrl = this.resolveTitleLink(entry, options.titleLink);
-        const title = entry.csl.title;
-        if (titleUrl && typeof title === "string" && title.trim()) {
-            out = this.linkTitle(out, title, titleUrl);
-        }
-        // Append badges
-        const badges = options.badges ?? [];
-        const badgeHtml = this.renderBadges(entry, badges);
-        if (badgeHtml) {
-            out += ` ${badgeHtml}`;
-        }
-        return out;
-    }
-    resolveTitleLink(entry, fields) {
-        const order = fields ?? ["url", "doi", "arxiv"];
-        for (const field of order) {
-            const value = entry.raw[field] ?? entry.csl[field.toUpperCase()] ?? entry.csl[field];
-            if (!value)
-                continue;
-            const raw = String(value).trim();
-            if (!raw)
-                continue;
-            if (/^https?:\/\//i.test(raw) || /^mailto:/i.test(raw)) {
-                return sanitizeUrl(raw);
-            }
-            if (field === "doi") {
-                const doi = raw.replace(/^doi:\s*/i, "");
-                return sanitizeUrl(`https://doi.org/${doi}`);
-            }
-            if (field === "arxiv") {
-                return sanitizeUrl(`https://arxiv.org/abs/${raw.replace(/v\d+$/, "")}`);
-            }
+    /**
+     * Render entries with citeproc, as `cite.format("bibliography")` does, but
+     * through an engine that has our variable wrapper: citeproc only accepts it
+     * when the engine is created. Styles and locales come from citation-js's
+     * registries, and the data is prepared the same way.
+     */
+    renderCslEntries(csl, lang) {
+        const data = Cite.util.downgradeCsl(csl);
+        const key = `${this.templateName}|${lang}`;
+        let engine = engines.get(key);
+        // citeproc is not re-entrant: a consumer function that formats with the
+        // same style while this engine renders gets an engine of its own.
+        if (!engine || busy.has(engine)) {
+            engine = createEngine(this.templateName, lang);
+            if (!engines.has(key))
+                engines.set(key, engine);
         }
-        return null;
-    }
-    linkTitle(html, title, url) {
-        const pattern = buildHtmlTextPattern(title);
-        if (!pattern)
-            return html;
-        const regex = new RegExp(pattern);
-        const tokens = html.split(/(<[^>]*>)/g);
-        let insideAnchor = false;
-        let insideScript = false;
-        let insideStyle = false;
-        let linked = false;
-        const output = [];
-        for (const token of tokens) {
-            if (token.startsWith("<")) {
-                const lower = token.toLowerCase();
-                if (/^<a\b/.test(lower))
-                    insideAnchor = true;
-                if (/^<\/a\b/.test(lower))
-                    insideAnchor = false;
-                if (/^<script\b/.test(lower))
-                    insideScript = true;
-                if (/^<\/script\b/.test(lower))
-                    insideScript = false;
-                if (/^<style\b/.test(lower))
-                    insideStyle = true;
-                if (/^<\/style\b/.test(lower))
-                    insideStyle = false;
-                output.push(token);
-                continue;
-            }
-            if (linked || insideAnchor || insideScript || insideStyle) {
-                output.push(token);
-                continue;
-            }
-            const replaced = token.replace(regex, (match) => {
-                linked = true;
-                return `<a href="${escapeAttr(url)}">${match}</a>`;
-            });
-            output.push(replaced);
+        const previous = current;
+        current = {
+            items: new Map(data.map(item => [String(item.id), item])),
+            wrap: (params, pre, str, post) => this.wrapVariable(params, pre, str, post),
+        };
+        busy.add(engine);
+        try {
+            engine.updateItems([]);
+            const ids = engine.updateItems(data.map(item => String(item.id)), true);
+            const bibliography = engine.makeBibliography();
+            if (!bibliography)
+                return [];
+            return bibliography[1].map((html, index) => [String(ids[index]), html]);
         }
-        return output.join("");
-    }
-    renderBadges(entry, badges) {
-        const parts = [];
-        for (const badge of badges) {
-            const rawValue = entry.raw[badge.field] ?? entry.custom[badge.field];
-            if (rawValue == null)
-                continue;
-            const strValue = String(rawValue);
-            let insertValue;
-            if (badge.match) {
-                const m = strValue.match(badge.match);
-                if (!m)
-                    continue;
-                insertValue = m[1] ?? m[0];
-            }
-            else {
-                insertValue = strValue;
-            }
-            const unsafeUrl = badge.url.replace(/\$1/g, insertValue);
-            const safeUrl = sanitizeUrl(unsafeUrl);
-            if (!safeUrl)
-                continue;
-            const cls = badge.className ? ` class="${escapeAttr(badge.className)}"` : "";
-            parts.push(`<a${cls} href="${escapeAttr(safeUrl)}">${escapeHtml(String(badge.label))}</a>`);
+        finally {
+            busy.delete(engine);
+            current = previous;
         }
-        if (parts.length === 0)
-            return "";
-        return `<span class="bib-links">${parts.join(" ")}</span>`;
     }
 }
 // ---------------------------------------------------------------------------
@@ -310,6 +395,151 @@ export function linkifyBareUrls(html) {
     return output.join("");
 }
 // ---------------------------------------------------------------------------
+// Fields and links
+// ---------------------------------------------------------------------------
+/**
+ * The value of a BibTeX field, and the only place fields are read. Names are
+ * case-insensitive. A field named like an eprint archive falls back to
+ * `eprint` when `eprinttype`/`archivePrefix` names that archive (biblatex and
+ * arXiv exports). Last, the CSL variable, which covers values citation-js
+ * derives (e.g. `URL` from `howpublished = {\url{…}}`).
+ */
+function fieldValue(entry, field) {
+    const name = field.toLowerCase();
+    let value = entry.raw[name] ?? entry.raw[field];
+    if (value == null) {
+        const archive = entry.raw.eprinttype ?? entry.raw.archiveprefix;
+        if (archive != null && String(archive).trim().toLowerCase() === name)
+            value = entry.raw.eprint;
+    }
+    value ??= entry.csl[field.toUpperCase()] ?? entry.csl[name];
+    const text = value == null ? "" : String(value).trim();
+    return text || undefined;
+}
+/** The links a badge yields for an entry: none, one, or one per `split` value. */
+function applyBadge(entry, badge) {
+    const value = fieldValue(entry, badge.field);
+    if (value === undefined)
+        return [];
+    const values = badge.split
+        ? value.split(badge.split).map(part => part.trim()).filter(Boolean)
+        : [value];
+    return values.flatMap((part) => {
+        let matched = part;
+        if (badge.match) {
+            const m = part.match(badge.match);
+            if (!m)
+                return [];
+            matched = m[1] ?? m[0];
+        }
+        const { url: template, label } = badge;
+        const url = safeUrl(typeof template === "function"
+            ? attributed(entry, () => template(matched, entry))
+            : template.replace(/\$1/g, () => matched));
+        if (!url)
+            return [];
+        return [{
+                value: matched,
+                url,
+                label: String(typeof label === "function" ? attributed(entry, () => label(matched, entry)) : label),
+            }];
+    });
+}
+const PRESETS_BY_FIELD = Object.fromEntries(Object.values(badgePresets).map(preset => [preset.field, preset]));
+/**
+ * The first title-link field that yields a URL. Fields with a preset use it,
+ * so a DOI title link and a DOI badge normalise the same way; other fields use
+ * a configured badge for that field, or must hold a URL themselves.
+ */
+function resolveTitleLink(entry, fields, badges) {
+    for (const field of fields) {
+        const name = field.toLowerCase();
+        const value = fieldValue(entry, field);
+        if (value === undefined)
+            continue;
+        const template = PRESETS_BY_FIELD[name] ?? badges.find(badge => badge.field.toLowerCase() === name);
+        const link = template ? applyBadge(entry, template)[0] : { value, url: safeUrl(value) };
+        if (link?.url)
+            return { kind: "title", field, value: link.value, url: link.url, entry };
+    }
+    return undefined;
+}
+function linkedFields(links) {
+    const fields = links.badges.map(badge => badge.field);
+    if (links.title)
+        fields.push(links.title.field);
+    return fields;
+}
+/**
+ * The CSL data a style gets to see: without the given (linked) fields, in either
+ * spelling (`doi`/`DOI`), and with a DOI it may print reduced to the bare DOI
+ * CSL expects. Exports write `doi:10…` or `https://doi.org/10…`, which a style
+ * would turn into `https://doi.org/doi:10…`.
+ */
+function displayCsl(csl, withheld) {
+    const copy = { ...csl };
+    for (const field of withheld) {
+        delete copy[field];
+        delete copy[field.toLowerCase()];
+        delete copy[field.toUpperCase()];
+    }
+    if (typeof copy.DOI === "string") {
+        const bare = copy.DOI.trim().match(badgePresets.doi.match)?.[1];
+        if (bare)
+            copy.DOI = bare;
+    }
+    return copy;
+}
+/** The fallback title link and the badges; the title link itself is added by citeproc's wrapper. */
+function decorate(html, titleLinked, links, options) {
+    let out = html;
+    // Never lose a link: a style that doesn't print the title gets its URL.
+    if (links.title && !titleLinked)
+        out += ` ${linkHtml(links.title, escapeHtml(links.title.url), options)}`;
+    if (links.badges.length && options.appendBadges !== false) {
+        const badges = links.badges.map(link => linkHtml(link, escapeHtml(link.label ?? ""), options));
+        out += ` <span class="${escapeAttr(options.badgeListClassName ?? "bib-links")}">${badges.join(" ")}</span>`;
+    }
+    return out;
+}
+/**
+ * Every `<a>` the library writes. `linkAttributes` may add attributes, add a
+ * class, or replace the URL; a replaced URL is checked like any other, and an
+ * unsafe one leaves the text unlinked.
+ */
+function linkHtml(link, inner, options) {
+    const extra = options.linkAttributes ? attributed(link.entry, () => options.linkAttributes(link)) : {};
+    const { class: extraClass, href, ...rest } = extra;
+    const url = typeof href === "string" ? safeUrl(href) : link.url;
+    if (!url)
+        return inner;
+    const className = [link.className, typeof extraClass === "string" ? extraClass : ""].filter(Boolean).join(" ");
+    return `<a${renderAttributes({ ...(className ? { class: className } : {}), href: url, ...rest })}>${inner}</a>`;
+}
+/** Visible text for comparing a rendered variable with a title: no tags, plain quotes, any case. */
+function plainText(html) {
+    return html
+        .replace(/<[^>]*>/g, "")
+        .replace(/&(?:amp|#38|#x26);/gi, "&")
+        .replace(/[\u2018\u2019]|&(?:#39|#x27|apos|rsquo|lsquo);/gi, "'")
+        .replace(/[\u201c\u201d\u201e]|&(?:quot|#34|#x22|ldquo|rdquo);/gi, '"')
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+/** Run a consumer function, naming the entry if it throws. */
+function attributed(entry, fn) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith(`entry ${entry.key}: `))
+            throw error;
+        throw new Error(`entry ${entry.key}: ${message}`, { cause: error });
+    }
+}
+// ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
 function readFileIfExists(input) {
@@ -347,42 +577,38 @@ function unwrapCslEntry(entryHtml) {
         return null;
     return (match[2] ?? "").trim();
 }
-function sanitizeUrl(url) {
+/** `http(s)`, `mailto` and relative URLs; anything with another scheme is dropped. */
+function safeUrl(url) {
     const trimmed = url.trim();
-    if (!trimmed)
-        return null;
-    if (/^https?:\/\//i.test(trimmed) || /^mailto:/i.test(trimmed)) {
+    if (/^(?:https?:\/\/|mailto:)/i.test(trimmed))
+        return trimmed;
+    if (/^(?:\/|\.\.?\/|#|\?)/.test(trimmed))
         return trimmed;
-    }
     return null;
 }
-function buildHtmlTextPattern(text) {
-    let pattern = "";
-    for (const ch of text) {
-        switch (ch) {
-            case "&":
-                pattern += "(?:&amp;|&#38;)";
-                break;
-            case "<":
-                pattern += "&lt;";
-                break;
-            case ">":
-                pattern += "&gt;";
-                break;
-            case '"':
-                pattern += "(?:&quot;|&#34;)";
-                break;
-            case "'":
-                pattern += "(?:&#39;|&apos;)";
-                break;
-            default:
-                pattern += escapeRegex(ch);
-        }
+/** `[year, month, day]` from CSL `issued`; missing parts are 0. */
+function issuedParts(entry) {
+    const parts = entry.csl.issued?.["date-parts"]?.[0];
+    if (!Array.isArray(parts))
+        return [entry.year ?? 0, 0, 0];
+    return [0, 1, 2].map(index => Number(parts[index]) || 0);
+}
+function compareKeys(a, b) {
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x < y)
+            return -1;
+        if (x > y)
+            return 1;
     }
-    return pattern;
+    return 0;
 }
-function escapeRegex(text) {
-    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Add a class to the attributes, after any the caller gave. */
+function withClass(attrs, className) {
+    const { class: extra, ...rest } = attrs;
+    const classes = [typeof extra === "string" ? extra : "", className].filter(Boolean).join(" ");
+    return { ...rest, class: classes };
 }
 function escapeAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");