wordcraft/docs/zotero.md

Zotero

WordCraft works with the Zotero desktop app the way Word does: Zotero's own citation dialog, all of its citation styles, automatic bibliography and refresh. Nothing to install in Zotero; it only has to be running. The Zotero tab in the ribbon has the buttons: Add/Edit Citation, Add Note, Add/Edit Bibliography, Refresh, Document Preferences and Unlink Citations (each runs one of the commands below).

Commands

Command	What it does
ui.zotero.addEditCitation	Add a citation at the caret, or edit the one the caret is in
ui.zotero.addEditBibliography	Add the bibliography at the caret, or edit it
ui.zotero.refresh	Update every citation and the bibliography
ui.zotero.setDocPrefs	Citation style, language, footnotes or in-text
ui.zotero.removeCodes	Unlink citations: keep the text, drop Zotero's codes
ui.zotero.addNote	Insert a Zotero note
ui.zotero.status	{busy, waitingForAnswer, last}
ui.zotero.answer	{"button": n}: answer a question Zotero is asking (OK/Yes 1, No/Cancel 0; with Yes/No/Cancel: Yes 2, No 1, Cancel 0)

They run in the app (and through the control channel and MCP bridged to the app). A command returns at once with {"started": …}; Zotero then works in its own window and WordCraft answers it in the background. All changes from one command are one undo step. If New or Open replaces the document while a command is running, Zotero's remaining calls for it get an error and the new document is left as it is.

From a terminal, against a file:

wordcraft-cli zotero refresh paper.docx --save paper.docx [--trace]

Two engine commands work with Zotero's fields without Zotero running:

• caret.pastCitation (Zotero › Move Past Citation) moves the caret to just after the citation it is in or before. Adjacent citations count as one. If there is none, it moves past the next citation.
• Read Aloud (review.readAloud, Review › Speech, Mod+Alt+Space) skips citations and the bibliography by default. This covers Zotero, Mendeley, EndNote and Word's own citation fields. The player window has previous/next sentence, pause, stop and speed (0.5–3×). Its commands are readAloud.playPause, .next, .previous, .stop, .speed {"value"}, .skipCitations {"value"} and .status. Set WORDCRAFT_SPEECH=off to keep it silent.

Switching between an in-text style and a note style in Document Preferences moves the citations: into new footnotes (or endnotes) at the same place, and back into the text where the note marks were; a note that held only the citation is removed.

Word compatibility

Citations are stored as Word's Zotero plugin stores them — fields with the code ADDIN ZOTERO_ITEM CSL_CITATION {…}, the bibliography as ADDIN ZOTERO_BIBL … CSL_BIBLIOGRAPHY, document preferences in the custom properties ZOTERO_PREF_1…n — so one document can be edited in Word and WordCraft in turn, with Zotero working in both. (Zotero talks to WordCraft over the protocol it uses for LibreOffice and calls the field type "Reference Mark" there; WordCraft keeps Word's "Field" in the file.)

Limits

• Zotero's "Bookmarks" field type isn't supported; keep the default.
• Zotero's document transfer (Export/Import Document) isn't needed and isn't supported.
• The web version can't reach Zotero (browsers can't open the socket).

Who can drive the document

Zotero's protocol has no handshake that proves the program on port 23116 is Zotero, and that program can read the citations and edit the open document. WordCraft limits who that can be. In short: every system gets the loopback rule; only Linux also checks that the listener isn't another user's. On Windows and macOS (and the BSDs) the loopback rule is the only check.

• Every system: it only connects to this computer (a loopback address such as 127.0.0.1); any other address is refused before connecting.
• Linux only: it checks, in the kernel's socket table (/proc/net/tcp, /proc/net/tcp6), that the program listening on the port runs as the same user as WordCraft, before sending anything. If another account on a shared machine took the port while Zotero wasn't running, WordCraft refuses with an error and the document isn't touched. When the table doesn't show the listener (WSL2 mirrored networking with Zotero running on Windows, a local proxy, a sandbox) or can't be read, its owner is unknown and only the loopback rule applies, as below.
• Windows, macOS and the BSDs: no same-user check. They have no such table to read without OS calls WordCraft doesn't make (it uses no unsafe code), so only the loopback rule applies there (and on Linux when the listener isn't in the table). Remaining risk: on a computer shared with other accounts, a program another user leaves on port 23116 while Zotero is closed would be taken for Zotero. An owner check for these systems is tracked in #3831. A program running as you is trusted on every system; it could change your documents anyway.
• wordcraft-cli zotero prints Zotero's messages (and --trace lines) with control characters, line breaks and backslashes shown as escapes (\n, \u{1b}, \\), so a peer can't forge other output or drive the terminal.

How it works

crates/zotero implements Zotero's published word-processor wire protocol (port 23116): client runs a session, Bridge answers Zotero's Document_* / Field_* calls against the session. The app (crates/ui-egui/src/zotero.rs) runs the socket on a thread and answers on the UI thread.