@xevos117/mcp-zotero 2.0.3 → 2.1.0

package/build/citation-injector/injector.js

@@ -1,195 +1,111 @@
-import JSZip from "jszip";
-import { readFile, writeFile } from "node:fs/promises";
-import { format, parse } from "node:path";
 import { isZoteroApiError } from "../types/zotero-types.js";
-import { generateZoteroFieldCode, generateBibliographyFieldCode } from "./field-codes.js";
-import { formatCitationText } from "./citation-formatter.js";
-import { regexEscape, unescapeXml } from "./xml-utils.js";
-import { normalizeZciteTags } from "./zcite-normalizer.js";
-import { EXISTING_PREFS_WARNING, PREFS_NOT_WRITTEN_WARNING, writeZoteroDocumentPrefs } from "./document-prefs.js";
 import { zoteroItemToCsl } from "../utils/csl-to-zotero.js";
-import { ZOTERO_KEY } from "../utils/zotero-keys.js";
-const REGENERATE_DOCX = "The file is not a Word document or is corrupted: create it again as .docx (e.g. with the docx npm package) and call again.";
-const NO_ZCITE_WARNING = 'No <zcite> placeholders found: the output is an unchanged copy. Write them in the document body as <zcite keys="ITEMKEY"/> ' +
-    "(headers, footers, footnotes and comments are not scanned).";
-function parseZciteMatches(documentXml) {
-    const findRegex = /&lt;zcite\s+[\s\S]*?\/&gt;/g;
-    const matches = [];
-    let findMatch;
-    while ((findMatch = findRegex.exec(documentXml)) !== null) {
-        const fullMatch = findMatch[0];
-        const cleanTag = unescapeXml(fullMatch);
-        const attrRegex = /(\w+)="([^"]*)"/g;
-        const attrs = {};
-        let attrMatch;
-        while ((attrMatch = attrRegex.exec(cleanTag)) !== null) {
-            // Unescape attribute values since the zcite tag is XML
-            // and values like "pp. 12 &amp; 15" need a second unescape
-            attrs[attrMatch[1]] = unescapeXml(attrMatch[2]);
+import { injectFile } from "./pipeline.js";
+import { itemCitekeys } from "./citekey-resolver.js";
+import { docxWriter } from "./formats/docx.js";
+import { odtWriter } from "./formats/odt.js";
+/** Scrittori per formato: Word (docx) e LibreOffice (odt). */
+const WRITERS = { docx: docxWriter, odt: odtWriter };
+/**
+ * ItemSource per il server: una GET per chiave dall'API Zotero; una chiave con 404 viene raccolta come
+ * assente dal chiamante, ogni altro errore interrompe subito (come prima in fetchCslData).
+ */
+export function zoteroItemSource(zoteroApi, libraryType, userId) {
+    return async (keys) => {
+        const cslData = new Map();
+        for (const key of keys) {
+            let response;
+            try {
+                response = await zoteroApi.library(libraryType, userId).items(key).get();
+            }
+            catch (err) {
+                if (isZoteroApiError(err) && err.response?.status === 404)
+                    continue;
+                throw err;
+            }
+            const zoteroItem = response.getData();
+            cslData.set(key, zoteroItemToCsl(zoteroItem));
         }
-        // Tolerate "KEY1, KEY2": a stray space would otherwise become part of the key (404 on fetch)
-        const keys = (attrs["keys"] ?? "").split(",").map((k) => k.trim()).filter(Boolean);
-        if (keys.length === 0)
-            continue;
-        matches.push({
-            fullMatch,
-            keys,
-            locator: attrs["locator"] || undefined,
-            prefix: attrs["prefix"] || undefined,
-            suffix: attrs["suffix"] || undefined,
-            num: attrs["num"] || undefined,
-        });
-    }
-    return matches;
+        return cslData;
+    };
 }
-async function fetchCslData(keys, zoteroApi, libraryType, userId) {
-    const cslData = new Map();
-    for (const key of keys) {
-        let response;
-        try {
-            response = await zoteroApi
-                .library(libraryType, userId)
-                .items(key)
-                .get();
-        }
-        catch (err) {
-            // Unknown keys are collected and reported together by the caller; any other failure aborts at once
-            if (isZoteroApiError(err) && err.response?.status === 404)
-                continue;
-            throw err;
+/** Cap on the fallback scan, so resolving an unknown citekey never walks an unbounded library. */
+const CITEKEY_SCAN_CAP = 5000;
+/** Record an item's citekeys into the exact/similar sets of each requested citekey. */
+function indexItemCitekeys(item, want) {
+    const key = typeof item.key === "string" ? item.key : undefined;
+    for (const ck of itemCitekeys(item)) {
+        const lc = ck.toLowerCase();
+        for (const [requested, w] of want) {
+            if (ck === requested) {
+                if (key)
+                    w.exact.add(key);
+            }
+            else if (lc === w.lower) {
+                w.similar.add(ck);
+            }
         }
-        const zoteroItem = response.getData();
-        cslData.set(key, zoteroItemToCsl(zoteroItem));
     }
-    return cslData;
 }
-function buildCitationItems(match, cslData, libraryType, userId) {
-    return match.keys.map((key, idx) => {
-        const itemData = cslData.get(key) ?? { type: "article-journal" };
-        const item = {
-            id: idx,
-            uris: [`http://zotero.org/${libraryType}s/${userId}/items/${key}`],
-            uri: [`http://zotero.org/${libraryType}s/${userId}/items/${key}`],
-            itemData,
-        };
-        if (match.locator)
-            item.locator = match.locator;
-        if (match.prefix)
-            item.prefix = match.prefix;
-        if (match.suffix)
-            item.suffix = match.suffix;
-        return item;
-    });
-}
-function replaceZciteInXml(xml, escapedZciteTag, fieldCodeXml) {
-    // Case A (preferred): tag is the sole content of a <w:r>
-    // Use [^<]*(?:<(?!/w:rPr>)[^<]*)* instead of .*? inside <w:rPr> to prevent
-    // matching across element boundaries in minified (single-line) XML.
-    const soloRunRegex = new RegExp(`<w:r>(?:<w:rPr>[^<]*(?:<(?!/w:rPr>)[^<]*)*</w:rPr>)?<w:t[^>]*>${regexEscape(escapedZciteTag)}</w:t></w:r>`);
-    if (soloRunRegex.test(xml)) {
-        return xml.replace(soloRunRegex, fieldCodeXml);
-    }
-    // Case B (fallback): tag is inline with other text
-    const inlineRegex = new RegExp(`(<w:r>(?:<w:rPr>([^<]*(?:<(?!/w:rPr>)[^<]*)*)</w:rPr>)?<w:t[^>]*>)([^<]*)${regexEscape(escapedZciteTag)}([^<]*)(</w:t></w:r>)`);
-    const inlineMatch = xml.match(inlineRegex);
-    if (inlineMatch) {
-        const rPr = inlineMatch[2]
-            ? `<w:rPr>${inlineMatch[2]}</w:rPr>`
-            : "";
-        const textBefore = inlineMatch[3];
-        const textAfter = inlineMatch[4];
-        let replacement = "";
-        if (textBefore) {
-            replacement += `<w:r>${rPr}<w:t xml:space="preserve">${textBefore}</w:t></w:r>`;
+/**
+ * CitekeyLookup per il server. Prima prova la ricerca `q=<citekey>&qmode=everything` (Extra compreso) e
+ * conferma lato client il match esatto (case-sensitive) sul campo `citationKey` o sulla riga
+ * `Citation Key:` di Extra. Se la ricerca non trova nessun match (l'indice full-text può non aver ancora
+ * indicizzato una voce appena creata, o `q` può non coprire Extra), ricade su una SCANSIONE paginata di
+ * `items/top` fino a CITEKEY_SCAN_CAP, che legge direttamente i dati delle voci (quindi vede subito anche
+ * una voce appena creata) e risolve in una sola passata tutti i citekey ancora mancanti. Un citekey che
+ * differisce solo per maiuscole/minuscole è raccolto come suggerimento per l'errore "not found".
+ */
+export function zoteroCitekeyLookup(zoteroApi, libraryType, userId) {
+    return async (citekeys) => {
+        const state = new Map();
+        for (const ck of citekeys)
+            state.set(ck, { exact: new Set(), similar: new Set(), lower: ck.toLowerCase() });
+        // Pass 1: one search per citekey (qmode=everything includes full text, so page up to 5 pages).
+        for (const [citekey, s] of state) {
+            for (let page = 0; page < 5; page++) {
+                const response = await zoteroApi
+                    .library(libraryType, userId)
+                    .items()
+                    .get({ q: citekey, qmode: "everything", limit: 100, start: page * 100 });
+                const items = response.getData() ?? [];
+                for (const it of items)
+                    indexItemCitekeys(it, state);
+                if (s.exact.size > 0 || items.length < 100)
+                    break;
+            }
         }
-        replacement += fieldCodeXml;
-        if (textAfter) {
-            replacement += `<w:r>${rPr}<w:t xml:space="preserve">${textAfter}</w:t></w:r>`;
+        // Pass 2 (fallback): for the citekeys the search did not resolve, scan items/top directly (reads item
+        // data, not the search index), one page, until all are resolved or the cap is reached.
+        const unresolved = new Map([...state].filter(([, s]) => s.exact.size === 0));
+        if (unresolved.size > 0) {
+            let start = 0;
+            for (;;) {
+                const response = await zoteroApi.library(libraryType, userId).items().top().get({ limit: 100, start });
+                const page = response.getData() ?? [];
+                if (page.length === 0)
+                    break;
+                for (const it of page)
+                    indexItemCitekeys(it, unresolved);
+                start += page.length;
+                if ([...unresolved.values()].every((s) => s.exact.size > 0))
+                    break;
+                if (start >= CITEKEY_SCAN_CAP || page.length < 100)
+                    break;
+            }
         }
-        return xml.replace(inlineRegex, replacement);
-    }
-    return xml;
+        const out = new Map();
+        for (const [ck, s] of state)
+            out.set(ck, { keys: [...s.exact], similar: [...s.similar] });
+        return out;
+    };
 }
-export async function injectCitations(filePath, zoteroApi, libraryType, userId, style) {
-    // Derive "<name>_cited<ext>" from the basename only: a directory containing ".docx" stays untouched
-    const { dir, name, ext } = parse(filePath);
-    const outputPath = format({ dir, name: `${name}_cited`, ext });
-    const fileBuffer = await readFile(filePath);
-    let zip;
-    try {
-        zip = await JSZip.loadAsync(fileBuffer);
-    }
-    catch (err) {
-        throw new Error(`Invalid .docx file: not a readable ZIP archive (${err instanceof Error ? err.message : String(err)}). ${REGENERATE_DOCX}`);
-    }
-    const documentEntry = zip.file("word/document.xml");
-    if (!documentEntry) {
-        throw new Error(`Invalid .docx file: word/document.xml not found. ${REGENERATE_DOCX}`);
-    }
-    let documentXml = await documentEntry.async("string");
-    documentXml = normalizeZciteTags(documentXml);
-    const matches = parseZciteMatches(documentXml);
-    if (matches.length === 0) {
-        const buffer = await zip.generateAsync({ type: "nodebuffer" });
-        await writeFile(outputPath, buffer);
-        return { outputPath, found: 0, injected: 0, warnings: [NO_ZCITE_WARNING] };
-    }
-    // Warn if using a numbered style but tags are missing the num attribute
-    const warnings = [];
-    if (style === "ieee" || style === "vancouver") {
-        const withNum = matches.filter((m) => m.num !== undefined).length;
-        if (withNum < matches.length) {
-            warnings.push(`Style '${style}' requires 'num' attribute on <zcite> tags. Found ${withNum}/${matches.length} tags with num. ` +
-                "Citations without num show [?] until the user runs Zotero → Refresh in Word; to get the numbers now, add " +
-                'num="N" (order of first citation) to every <zcite> in the original file and run again.');
-        }
-    }
-    // Collect all unique item keys
-    const uniqueKeys = new Set(matches.flatMap((m) => m.keys));
-    // Keys from the document go into API URL paths (one GET per key) and Zotero URIs: only well-formed Zotero
-    // keys, so a crafted <zcite> cannot point the request at another endpoint ("../", "?", "&"), and a key Zotero
-    // would reject never reaches the document. The skill's inject.js applies the same check
-    const invalid = [...uniqueKeys].filter((k) => !ZOTERO_KEY.test(k));
-    if (invalid.length > 0) {
-        throw new Error(`Invalid Zotero item key(s) in <zcite>: ${invalid.join(", ")} (a key is 8 characters from 23456789ABCDEFGHIJKLMNPQRSTUVWXYZ). ` +
-            "No file was written. Use the keys returned by search_library, add_items_by_doi or add_items.");
-    }
-    // Fetch CSL data from Zotero
-    const cslData = await fetchCslData(uniqueKeys, zoteroApi, libraryType, userId);
-    // No placeholder citations in the user's document: a citation of a nonexistent item fails the injection,
-    // like the skill's inject.js with a key missing from metadata.json
-    const missingKeys = [...uniqueKeys].filter((k) => !cslData.has(k));
-    if (missingKeys.length > 0) {
-        throw new Error(`${missingKeys.length} cited key(s) not found in the library: ${missingKeys.join(", ")}. No file was written. ` +
-            "Fix these keys in the document (find existing items with search_library, or add the missing ones with add_items_by_doi " +
-            "or add_items) and call again; for a group library pass library_type and library_id.");
-    }
-    // Replace each zcite tag with a field code
-    let injected = 0;
-    for (const match of matches) {
-        const citationItems = buildCitationItems(match, cslData, libraryType, userId);
-        const itemDataList = match.keys.map((k) => cslData.get(k) ?? { type: "article-journal" });
-        const formattedText = formatCitationText(itemDataList, style, match);
-        const fieldCodeXml = generateZoteroFieldCode(citationItems, formattedText);
-        const newXml = replaceZciteInXml(documentXml, match.fullMatch, fieldCodeXml);
-        if (newXml !== documentXml) {
-            documentXml = newXml;
-            injected++;
-        }
-    }
-    // Append bibliography before </w:body>
-    const biblXml = generateBibliographyFieldCode();
-    documentXml = documentXml.replace("</w:body>", `${biblXml}</w:body>`);
-    // Document preferences (style, field type) where Zotero for Word reads them: no Document Preferences dialog
-    // on the first Refresh, the injected style is applied (H-W1)
-    zip.file("word/document.xml", documentXml);
-    const prefs = await writeZoteroDocumentPrefs(zip, style);
-    if (prefs === "kept")
-        warnings.push(EXISTING_PREFS_WARNING);
-    if (prefs === "skipped")
-        warnings.push(PREFS_NOT_WRITTEN_WARNING);
-    // Save
-    const buffer = await zip.generateAsync({ type: "nodebuffer" });
-    await writeFile(outputPath, buffer);
-    return { outputPath, found: matches.length, injected, warnings };
+/**
+ * Sostituisce i segnaposto <zcite> di un documento con le citazioni native di Zotero (field code Word per
+ * docx, reference mark LibreOffice per odt) e aggiunge la bibliografia. Involucro del nucleo comune
+ * (pipeline + scrittore di formato). `format` di default docx: il percorso Word non cambia. Se il
+ * documento non ha <zcite> ma marcatori Pandoc `[@…]`, usa il ramo pandoc (risoluzione dei citekey inclusa).
+ */
+export async function injectCitations(filePath, zoteroApi, libraryType, userId, style, format = "docx") {
+    return injectFile(filePath, WRITERS[format] ?? docxWriter, zoteroItemSource(zoteroApi, libraryType, userId), { libraryType, userId, style }, zoteroCitekeyLookup(zoteroApi, libraryType, userId));
 }

package/build/citation-injector/model.js

@@ -0,0 +1,9 @@
+/** Errore dell'iniezione con un codice stabile; il messaggio resta quello mostrato all'utente. */
+export class InjectionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "InjectionError";
+    }
+}

package/build/citation-injector/odt-normalizer.js

@@ -0,0 +1,169 @@
+import { XMLParser, XMLBuilder } from "fast-xml-parser";
+/**
+ * Pre-elabora content.xml di un .odt per unire i tag <zcite> che LibreOffice ha spezzato tra più
+ * `text:span` (p.es. per un cambio di formato a metà tag), così parseZciteTags e lo scrittore ODT li
+ * trovano contigui. Analogo a zcite-normalizer.ts per Word.
+ *
+ * I commenti (office:annotation) e le note (text:note) sono esclusi come in Word: un <zcite> lì dentro
+ * non viene iniettato. Un `text:s text:c="n"` vale n spazi nell'estrazione del testo.
+ *
+ * Se non trova tag spezzati restituisce la stringa originale invariata (zero rischio di differenze di
+ * round-trip nell'XML).
+ */
+const ZCITE_PATTERN = /&lt;zcite\s+[\s\S]*?\/&gt;/;
+// A complete Pandoc bracketed citation inside one text node (no tag `<`); see zcite-normalizer.ts.
+const PANDOC_PATTERN = /\[[^\]<]*@[^\]<]*\]/;
+const PARSER_OPTIONS = {
+    preserveOrder: true,
+    ignoreAttributes: false,
+    processEntities: false,
+    trimValues: false,
+    parseTagValue: false,
+    parseAttributeValue: false,
+};
+const BUILDER_OPTIONS = {
+    preserveOrder: true,
+    ignoreAttributes: false,
+    processEntities: false,
+    format: false,
+    suppressEmptyNode: false,
+    suppressBooleanAttributes: false,
+};
+/** Sottoalberi da non toccare: commenti e note. */
+const MASKED = new Set(["office:annotation", "text:note"]);
+/** Testo visibile di un text:span: #text diretti più `text:s text:c=n` come n spazi. */
+function extractSpanText(spanChildren) {
+    let text = "";
+    for (const child of spanChildren) {
+        if ("#text" in child)
+            text += String(child["#text"]);
+        else if ("text:s" in child) {
+            const c = Number(child[":@"]?.["@_text:c"] ?? "1");
+            text += " ".repeat(Number.isFinite(c) && c > 0 ? c : 1);
+        }
+    }
+    return text;
+}
+function isSpan(node) {
+    return "text:span" in node;
+}
+/** Un text:span che porta del testo (ha #text o text:s). */
+function spanHasText(spanChildren) {
+    return spanChildren.some((c) => "#text" in c || "text:s" in c);
+}
+/** Gruppi di text:span consecutivi (con testo) figli diretti di un text:p/text:h. */
+function collectConsecutiveSpanGroups(children) {
+    const groups = [];
+    let current = null;
+    const flush = () => {
+        if (current && current.texts.length >= 2)
+            groups.push(current);
+        current = null;
+    };
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (isSpan(child) && spanHasText(child["text:span"])) {
+            const text = extractSpanText(child["text:span"]);
+            if (current) {
+                current.endIndex = i;
+                current.texts.push(text);
+            }
+            else {
+                current = { startIndex: i, endIndex: i, texts: [text] };
+            }
+            continue;
+        }
+        flush();
+    }
+    flush();
+    return groups;
+}
+/** Trova un <zcite> che attraversa più span del gruppo; ritorna l'intervalo [startOffset,endOffset]. */
+function findSplitZcite(group, pattern) {
+    const { texts } = group;
+    for (let start = 0; start < texts.length; start++) {
+        let concat = "";
+        for (let end = start; end < texts.length; end++) {
+            concat += texts[end];
+            if (end <= start)
+                continue;
+            const m = pattern.exec(concat);
+            if (m) {
+                const matchStart = m.index;
+                const matchEnd = m.index + m[0].length;
+                const lastStart = concat.length - texts[end].length;
+                if (matchStart < lastStart && matchEnd > lastStart)
+                    return { startOffset: start, endOffset: end };
+            }
+        }
+    }
+    return null;
+}
+/** Unisce gli span [absStart..absEnd] in uno solo (attributi del primo, testo concatenato come #text). */
+function mergeSpansInPlace(children, group, startOffset, endOffset) {
+    const absStart = group.startIndex + startOffset;
+    const absEnd = group.startIndex + endOffset;
+    const count = absEnd - absStart + 1;
+    let merged = "";
+    for (let i = absStart; i <= absEnd; i++)
+        merged += extractSpanText(children[i]["text:span"]);
+    const newSpan = { "text:span": [{ "#text": merged }] };
+    const firstAttrs = children[absStart][":@"];
+    if (firstAttrs)
+        newSpan[":@"] = firstAttrs;
+    children.splice(absStart, count, newSpan);
+}
+function normalizeParagraph(children, pattern) {
+    let modified = false;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const group of collectConsecutiveSpanGroups(children)) {
+            const split = findSplitZcite(group, pattern);
+            if (split) {
+                mergeSpansInPlace(children, group, split.startOffset, split.endOffset);
+                modified = true;
+                changed = true;
+                break;
+            }
+        }
+    }
+    return modified;
+}
+function walk(nodes, pattern) {
+    let modified = false;
+    for (const node of nodes) {
+        const tag = Object.keys(node).find((k) => k !== ":@" && k !== "#text");
+        if (tag && MASKED.has(tag))
+            continue; // non toccare commenti e note
+        if (tag === "text:p" || tag === "text:h") {
+            if (normalizeParagraph(node[tag], pattern))
+                modified = true;
+        }
+        for (const key of Object.keys(node)) {
+            if (key === ":@" || key === "#text")
+                continue;
+            const value = node[key];
+            if (Array.isArray(value) && walk(value, pattern))
+                modified = true;
+        }
+    }
+    return modified;
+}
+function normalizeOdt(contentXml, pattern, quick) {
+    if (!contentXml.includes(quick))
+        return contentXml;
+    const parsed = new XMLParser(PARSER_OPTIONS).parse(contentXml);
+    if (!walk(parsed, pattern))
+        return contentXml;
+    return new XMLBuilder(BUILDER_OPTIONS).build(parsed);
+}
+export function normalizeOdtZciteTags(contentXml) {
+    return normalizeOdt(contentXml, ZCITE_PATTERN, "zcite");
+}
+/** Merge Pandoc `[@…]` markers split across text:span in an ODT, mirror of normalizePandocMarkers. */
+export function normalizeOdtPandocMarkers(contentXml) {
+    if (!contentXml.includes("[") || !contentXml.includes("@"))
+        return contentXml;
+    return normalizeOdt(contentXml, PANDOC_PATTERN, "[");
+}

package/build/citation-injector/pandoc-body.js

@@ -0,0 +1,99 @@
+import { unescapeXml } from "./xml-utils.js";
+/**
+ * Finds Pandoc-style citation markers in an already-normalized document body and turns them into neutral
+ * CitationRequest, for the Pandoc branch of inject_citations. Markers are read ONLY from visible text
+ * (docx `<w:t>` content, odt element content) — never from field codes (`<w:instrText>`), attributes or a
+ * reference mark's CSL JSON — so a second call on a `_cited` file does not treat a "@" inside an existing
+ * field (e.g. a title "Twitter: @handle") as a new citation.
+ *
+ * `raw` is the marker exactly as it appears in the body (XML-escaped), so the format writer's replaceTag
+ * can locate and replace it; `[` `]` `@` are never XML-escaped, only prose inside a marker may carry
+ * entities, which are unescaped before use.
+ *
+ * Bracketed forms — `[@KEY]`, `[@K1; @K2]`, `[see @KEY, p. 12]`, `-@KEY` — mark `inline: false`; a bare
+ * `@KEY` / `-@KEY` marks `inline: true`. An inline that does not resolve is later kept as text with a
+ * warning (not an error); an unknown bracketed key stays an error.
+ */
+// Bracketed citekeys: Better BibTeX keys that begin and end on an alphanumeric/underscore, with internal
+// punctuation only (so a trailing sentence "." or "," is not swallowed). Zotero keys are a strict subset.
+const KEY = "[A-Za-z0-9_](?:[A-Za-z0-9_:.#$%&+?~/-]*[A-Za-z0-9_])?";
+// Inline citekeys are conservative (no `/`, `#`, …) so paths and handles like @angular/core don't become
+// one long key; whatever is captured and does not resolve is kept as text anyway.
+const INLINE_KEY = "[A-Za-z0-9_](?:[A-Za-z0-9_:.-]*[A-Za-z0-9_])?";
+// Inline marker: `@key` / `-@key` not preceded by a word char, `_`, `/` or `.` (so emails "a@b", paths
+// "x/@y", "a.@b" and "foo_@bar" are not citations).
+const INLINE_RE = new RegExp(`\\[([^\\]<]*@[^\\]<]*)\\]|(?<![A-Za-z0-9_/.])(-?)@(${INLINE_KEY})`, "g");
+// Inside a bracket, a `@key` is a citation only at the start of a part or after whitespace/`;` — never after
+// `/`, `_`, `.` or an alphanumeric (so a URL "http://x/@user" in a bracket is not a citation key).
+const KEY_RE = new RegExp(`(^|[\\s;])(-?)@(${KEY})`);
+const LOCATOR_RE = /^(?:p{1,2}\.|pp?\b|pages?\b|chap\.?|ch\.|sec\.?|§|fig\.?|no\.?|vol\.?|art\.?)/i;
+/** Parse the already-unescaped inner text of a `[...]` marker into a request (one entry's prefix/locator/suffix). */
+function parseBracketInner(inner) {
+    const parts = inner.split(";");
+    const keys = [];
+    let prefix;
+    let suffix;
+    let locator;
+    let suppressAuthor = false;
+    for (const part of parts) {
+        const mm = KEY_RE.exec(part);
+        if (!mm)
+            continue;
+        const at = mm.index + mm[1].length; // position of the (optional) "-" / "@"
+        keys.push(mm[3]);
+        if (parts.length === 1) {
+            const before = part.slice(0, at).trim();
+            if (before)
+                prefix = before;
+            suppressAuthor = mm[2] === "-";
+            const after = part.slice(at + mm[2].length + 1 + mm[3].length).replace(/^[.,;:]*\s*/, "").trim();
+            if (after) {
+                if (LOCATOR_RE.test(after))
+                    locator = after;
+                else
+                    suffix = after;
+            }
+        }
+    }
+    if (keys.length === 0)
+        return null;
+    return { keys, prefix, suffix, locator, suppressAuthor, inline: false };
+}
+/** Parse markers in a single visible-text string (XML-escaped), in order. */
+export function parsePandocCitesInText(text) {
+    const requests = [];
+    const re = new RegExp(INLINE_RE.source, "g");
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        if (m[1] !== undefined) {
+            const parsed = parseBracketInner(unescapeXml(m[1]));
+            if (parsed)
+                requests.push({ ...parsed, raw: m[0] });
+        }
+        else {
+            requests.push({ keys: [m[3]], suppressAuthor: m[2] === "-", inline: true, raw: m[0] });
+        }
+    }
+    return requests;
+}
+/** Visible-text segments of a body, in document order: `<w:t>` content for docx, element content for odt. */
+function visibleTexts(body, format) {
+    const out = [];
+    // docx: only run text (<w:t>…</w:t>) — never <w:instrText> field codes. odt: element content between
+    // ">" and "<" — the CSL JSON of a reference mark lives in an attribute, so it is excluded.
+    const re = format === "docx" ? /<w:t\b[^>]*>([\s\S]*?)<\/w:t>/g : />([^<]*)</g;
+    let m;
+    while ((m = re.exec(body)) !== null)
+        out.push(m[1]);
+    return out;
+}
+export function parsePandocCitesInBody(body, format) {
+    const requests = [];
+    for (const text of visibleTexts(body, format))
+        requests.push(...parsePandocCitesInText(text));
+    return requests;
+}
+/** Count of Pandoc markers in a body (for the mixed-document warning in the zcite branch). */
+export function countPandocMarkers(body, format) {
+    return parsePandocCitesInBody(body, format).length;
+}