WASM plugin API: library, search, batching, notifier
Area library. WIT: plugin-api/wit/library.wit. Phase 1 is design only. “Needs core” in a status means the WIT is written but Zinc’s core (core/src/, core/schema.sql) does not serve the feature yet; that is fine for phase 1.
Sources read: Zotero chrome/content/zotero/xpcom/data/*.js (items, collections, searches, tags, relations, libraries, groups, notes, itemFields, cachedTypes, creators, feeds), search conditions (data/searchConditions.js, 59 conditions), attachments.js, fulltext.js, cite.js, quickCopy.js, duplicates.js, notifier.js, db.js, translation/translators.js; Zinc’s core/schema.sql, core/src/api-types.ts, docs/developer-guide/http-api.md, database.md, and the earlier compat layer (gpui-ui/src/plugins/zotero/). Zotero.Translate itself and Zotero.Utilities.Item live in git submodules that the sparse checkout does not contain; their rows come from Zotero’s public API, not from the checked-out source.
Interfaces in library.wit
| Interface | Direction | What |
|---|---|---|
library |
import | libraries, items (query, get), collections, tags, relations, saved searches, duplicates, trash, apply (atomic batch) |
attachments |
import | attachment info, file bytes, import / link / replace / rename, Find Full Text, reader view state |
fulltext |
import | indexed text, index state, set content, search |
schema |
import | item types, fields, creator types |
cite |
import | styles, bibliography / citation formatting, Quick Copy |
translate |
import | list / run import, export, lookup, web translators |
sync-control |
import | sync state, start a sync |
data-utils |
import | dates, CSL JSON, note title, display title, extra parsing, identifier extraction |
notifier |
import | subscribe, unsubscribe, trigger, and the event types |
notifier-handler |
export | the plugin implements on-events(subscription, batch) |
world.wit (lifecycle) must import library, attachments, fulltext, schema, cite, translate, sync-control, data-utils, notifier and export notifier-handler. The world needs the export and the import to be different interfaces because a world cannot export and import the same interface name; that is why the callback is not inside notifier.
Types come from types.wit: item-key, collection-key, search-key, library-id, json, error, plugin-id, epoch-ms. No local error type was needed.
1. Parity table
Status: covered, partial (what is missing is stated), not planned (why, and what to do instead).
Items and item objects (data/items.js, data/item.js, data/dataObjects.js, data/dataObject.js)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.Items.get/getAsync/getByLibraryAndKey(Async) (dataObjects.js) |
library.get-items(keys, get-options) returns item JSON |
covered. Numeric itemID is not exposed: Zinc has none; keys are unique across libraries |
Zotero.Items.getAll, getAllIDs/Keys, getDeleted |
library.query-items, query-keys, scope all / trash |
covered |
Item.getField/setField/getFields, getCreators/setCreators/getCreator*, getTags, getCollections, getRelations, getNote, getAttachments |
fields of item JSON from get-items; changes through apply.update-item |
covered. A plugin edits JSON, not an object with setters |
Item.toJSON, Item.fromJSON, toResponseJSON (item.js) |
item JSON is the Web API data object |
covered (see design note on version and dateModified) |
Item.saveTx, item.save() inside executeTransaction (dataObject.js) |
library.apply with create-item / update-item |
covered |
Item.hasChanged, Item.diff, multiDiff |
item-update.expected-modified for conflict detection; diff is guest-side on JSON |
partial: no diff helper |
Item.clone, Zotero.Items.copyChildItems |
create-item with JSON copied by the plugin; duplicate exists in the core (POST /api/items/:key/duplicate) but has no WIT call |
partial: add duplicate-item if wanted (open question 4) |
Item.moveToLibrary, Zotero.Items.moveChildItems, Attachments.moveAttachmentToLibrary/copyAttachmentToLibrary |
create-item with library, then trash-items |
partial. A real move keeps keys; Zinc keys must stay globally unique, so a move is a copy plus trash. Needs core for files |
Item.isRegularItem/isNote/isAttachment/isTopLevelItem/isInTrash/isAnnotation, topLevelItem, Zotero.Items.getTopLevel/keepTopLevel/keepParents |
itemType, parentItem, deleted in JSON; item-summary.parent-key, in-trash |
covered, guest-side helpers |
Item.numChildren/numNotes/numAttachments/numAnnotations |
item-summary.attachment-count, note-count; get-children |
covered (annotation count: see reader) |
Item.getDisplayTitle, getTabTitle |
data-utils.display-title |
covered (tab title is UI) |
Item.getNoteTitle, Zotero.Notes.noteToTitle |
data-utils.note-to-title |
covered |
Item.setNote, note HTML |
note field of item JSON in apply |
covered |
Zotero.Items.getFirstCreatorFromJSON/FromData, getSortTitle |
data-utils.first-creator, sort-title |
covered |
Item.addRelatedItem/removeRelatedItem, getRelations, addRelation, removeRelation, setRelations |
apply.add-related / remove-related; relations in item JSON |
covered for items. Zinc’s core only knows dc:relation as a UI concept but stores relations JSON verbatim |
Zotero.Relations.getByPredicateAndObject/getByObject (relations.js) |
library.find-by-relation |
partial. Needs core: no relation index (JSON in items.data) |
Item.getLinkedItem/addLinkedItem, Collection.getLinkedCollection |
relations (owl:sameAs) in JSON; find-by-relation |
partial: no direct helper, same core gap |
Zotero.Items.addToPublications/removeFromPublications, Item.setPublications |
apply.add-to-publications, remove-from-publications; scope publications |
partial. Core lists publications (publications=1) but has no write route |
Item.getExtraField, Zotero.Utilities.Internal.extractExtraFields |
data-utils.parse-extra |
covered |
Item.getUsedFields, getFieldsNotInType, setType |
JSON edit and schema.get-schema |
covered (type change by update-item with new itemType; core must drop invalid fields: needs core check) |
Item.getImageSrc, getItemTypeIconName |
UI | not planned here: icons belong to the ui area |
Item.migrateExtraFields, updateCreatedByUser |
internal migration | not planned: Zotero upgrade code, not a plugin API |
Zotero.Items.getLastRead/getLastReadAttachmentIDs/clearAllLastRead, Item.getItemLastRead |
attachment-info.last-read |
partial. Needs core: no lastRead column |
Zotero.Items.findMissingLinkedFiles, numDistinctFileAttachmentsForLabel |
query-items plus attachments.get-info (file-exists) |
partial: no single call |
Zotero.Items.merge, Zotero.Duplicates.findAll/find/findAllInSet, getSearchObject |
library.merge-items, find-duplicates |
covered |
Zotero.Duplicates “not a duplicate” marks |
library.mark-not-duplicates |
covered |
Zotero.Items.trash/trashTx, Item.deleted = true |
apply.trash-items |
covered |
Item.deleted = false (restore), Zotero.Items.undoTrash |
apply.restore-items |
covered |
Item.erase/eraseTx, Zotero.Items.erase |
apply.erase-items (must be trashed first) |
covered |
Zotero.Items.emptyTrash, purge |
library.empty-trash |
covered. purge (orphan value cleanup) is internal |
Zotero.Items.hasDeleted, trash listing |
query-items with scope trash |
covered |
item.version, synced, dateModified handling, skipDateModifiedUpdate |
version and dateModified in JSON; host stamps dateModified on every change |
partial: no skipDateModifiedUpdate; a plugin cannot back-date (by design, see notes) |
Item types used by plugins: annotation items (getAnnotations, isAnnotation, Zotero.Items.get(annotationID)) |
none in this area | partial: annotations are reader data in Zinc (annotations table). reader.wit’s annotations interface is the only route (typed, batched, with the same field names); get-items, query-items and apply answer invalid-argument for an annotation key |
Collections (data/collections.js, data/collection.js)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.Collections.getByLibrary/getByParent/get |
library.list-collections |
covered |
Collection.getChildCollections/getDescendents, hasChildCollections |
list-collections (parent) |
covered, guest-side |
Collection.getChildItems/hasChildItems/hasItem/hasDescendent |
library.get-collection-items(key, recursive); scope collection |
covered |
Collection.name = / parentID = / saveTx |
apply.create-collection, update-collection |
covered |
Collection.addItem(s)/removeItem(s) |
apply.add-to-collection, remove-from-collection |
covered |
Collection.erase / eraseTx, deleteItems |
apply.erase-collection(trash-items) |
covered |
Collection.trash, collections in the trash (Zotero 7), Zotero.Collections deleted flag |
none | partial: Zinc deletes collections for good (core/schema.sql has no deleted flag). Needs core |
Collection.toJSON/fromJSON, serialize |
collection-info |
covered (record, not JSON) |
Zotero.Collections.getRecent/addToRecent, registerChildCollection |
UI state | not planned: UI cache and recent-list for the collection picker |
| Collection relations | relations not on collection-info |
partial. Needs core: collections have no relations column |
Collection.version, sync fields |
collection-info.version |
covered |
Tags (data/tags.js)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.Tags.getAll/getAllWithin/getTagItems |
library.list-tags(library, within); query-items with tags |
covered |
Item.addTag/removeTag/setTags/hasTag/replaceTag/removeAllTags, tag type |
apply.add-tags, remove-tags, update-item.patch.tags; tag-kind |
covered |
Zotero.Tags.rename |
library.rename-tag |
covered |
Zotero.Tags.removeFromLibrary, removeAutomaticFromLibrary, purge |
library.delete-tags, delete-automatic-tags |
covered |
Zotero.Tags.getColor/getColors/setColor/getColorByPosition, toggleItemsListTags |
library.get-tag-colors, set-tag-colors |
partial: colour list only. Emoji tags and emojiTag flags are UI display, left to ui |
Zotero.Tags.extractEmojiForItemsList, compareTagsOrder, equals, cleanData |
n/a | not planned: display and string helpers; the plugin can reimplement |
Saved searches and searching (data/search.js, searches.js, searchConditions.js, quicksearch)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.Search.addCondition(name, operator, value, required), getConditions, setScope, fromJSON/toJSON |
search-definition / search-condition |
partial. The record carries any of Zotero’s 59 condition names, but the core compiler (core/src/searches/compile.ts) supports a subset (title, creator, year, date fields, publicationTitle, itemType, tag, collection, note, attachmentFileType, fulltextContent, anyField, schema fields; no groupStart/groupEnd, numberfield, lastRead, annotation*, retracted, tempTable). Needs core |
Zotero.Search.search() (item ids), getSQL |
library.query-items / query-keys with search |
covered for supported conditions; getSQL is not planned (no SQL). Zotero 10 added condition groups and removed fulltextWord (use fulltextContent) and migrated childNote to note; Zinc accepts fulltextContent and note, and has no group conditions yet (see the first row) |
joinMode any/all, includeParentsAndChildren, recursive, noChildren, includeDeleted, required |
search-options, search-condition.required |
covered |
Zotero.Search.setScope(search) (search within search) |
item-query.scope = saved-search plus search |
partial: nesting one saved search in another via a savedSearch condition is not in the core |
Zotero.SearchConditions.getStandardConditions/getLocalizedName |
library.list-search-conditions |
covered |
Zotero.Searches.getAll/getByLibrary/get, getNextName |
library.list-saved-searches, get-saved-search |
covered. Zotero 10 lets several saved searches and collections be selected at once (getSelectedSavedSearches, getSelectedCollections); a Zinc plugin gets lists from extend.context and runs one item-query per scope (zotero-versions.md) |
Search.name = / saveTx / erase |
apply.create-saved-search, update-saved-search, erase-saved-search |
covered |
Quick search modes (quicksearch-titleCreatorYear/fields/everything, Zotero.Search quick) |
item-query.text with text-mode |
covered |
Zotero.Search.hasPostSearchFilter, tempTable condition |
n/a | not planned: internal SQL planner |
Search results with resultLevel, fulltextContent |
item-query.search, fulltext.search |
partial: resultLevel is not in the core |
Aggregates (SELECT ... GROUP BY) written by plugins in SQL |
library.facets |
partial: one grouping field per call, listed fields only |
Libraries and groups (data/libraries.js, library.js, groups.js)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.Libraries.getAll/get/exists/getName/getType, isEditable, isFilesEditable, hasTrash |
library.list-libraries → library-info |
covered |
Zotero.Groups.getAll/get/getByLibraryID, getGroupIDFromLibraryID, getPermissionsFromJSON |
library-info.group-id, editable, files-editable |
covered |
Zotero.Libraries.getVersion/setVersion/getLastSyncTime, Library.updateLastSyncTime, incrementClientVersion |
n/a | not planned: sync internals. Use sync-control.get-state |
Library.hasItems/hasCollections/hasSearches, waitForDataLoad, getDataLoaded |
n/a | not planned: Zinc has no lazy data loading phases; calls always see the data |
Library.saveTx/eraseTx, Zotero.Groups.register (create/delete libraries) |
n/a | not planned: libraries are created by sync from zotero.org, not by plugins |
Zotero.Libraries.userLibraryID, Zotero.Groups selected library |
library-id 1 |
covered |
Schema and types (data/itemFields.js, cachedTypes.js, creators.js)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.ItemTypes.getAll/getName/getID/getTypesForItemType, getLocalizedString |
schema.get-schema |
partial: English labels only. Localized labels need the host’s l10n (lifecycle) |
Zotero.ItemFields.getAll/getName/getItemTypeFields/getBaseMappedFields/isValidForType/isBaseField, isDate/isLong/isMultiline/isAutocompleteField |
schema.field-info (base-field, is-date, is-long, is-multiline) |
partial. Needs core: /api/schema has no is-* flags; the host can hardcode them. Autocomplete flag omitted |
Zotero.CreatorTypes.getTypesForItemType/getPrimaryIDForType, isValidForItemType |
schema.creator-type-info |
covered |
Zotero.ItemTypes.add, custom types and fields (isCustom) |
n/a | not planned: Zinc follows Zotero’s schema. A plugin stores its own data in extra, relations or its private storage (lifecycle) |
Zotero.Creators.get/getIDFromData/getItemsWithCreator/countItemAssociations/updateCreator, Creators.cleanData |
n/a | not planned: Zinc stores creators inside item JSON, with no creator table. Rename a creator across items with query-items (condition creator) plus apply.update-item |
Zotero.DataObjectUtilities, Zotero.CollectionTreeRow |
n/a | not planned: Zotero UI internals |
Attachments (attachments.js, item.js attachment methods)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Item.getAttachmentLinkMode/MIMEType/Charset, isPDFAttachment, isFileAttachment, isLinkedFileAttachment, isImportedAttachment, isSnapshotAttachment, isEPUBAttachment, getFilename, fileExists, getAttachmentLastPageIndex |
attachments.get-info → attachment-info |
partial: charset and last-read need core |
Item.getFilePath/getFilePathAsync/getFile |
attachment-info.path (permission library.files.paths) |
covered, permission-gated |
Attachments.getStorageDirectory(ByID/ByLibraryAndKey), createDirectoryForItem, createTemporaryStorageDirectory, fixPathSlashes, getBaseDirectoryRelativePath, resolveRelativePath |
n/a | not planned: a plugin has no file system. Ask the host to read, write, import or rename instead |
Attachments.hasMultipleFiles/getNumFiles/getTotalFileSize |
attachments.storage-of |
covered |
Attachments.importFromFile |
attachments.import-bytes, file-writer |
covered. A plugin passes bytes, not a path |
Attachments.linkFromFile, linkFromFileWithRelativePath |
attachments.link-file |
covered (path permission) |
Attachments.importFromURL, downloadFile, importSnapshotFromFile |
attachments.import-from-url |
covered. Network permission applies |
Attachments.linkFromURL |
attachments.link-url |
covered |
Attachments.importFromDocument, linkFromDocument, importFromSnapshotContent, importEmbeddedImage, copyEmbeddedImage |
import-bytes with HTML bytes |
partial: no DOM document; embedded note images have no WIT call and the core does not store them separately. Needs core |
Attachments.importFromNetworkStream, createURLAttachmentFromTemporaryStorageDirectory |
n/a | not planned: Firefox network stream internals |
Item.renameAttachmentFile, Attachments.getFileBaseNameFromItem, getAttachmentRenameTemplate, shouldAutoRenameFile, isAutoRenameFilesEnabledForLibrary, rename setting |
attachments.rename-file, rename-by-template |
partial: template read and auto-rename settings are prefs; the prefs interface (lifecycle) should expose them |
Item.relinkAttachmentFile, deleteAttachmentFile |
attachments.relink-file, delete-file |
covered |
Attachments.convertLinkedFileToStoredFile |
read-file + import-bytes + trash |
partial: no single call. Needs core |
Item.getBestAttachment(s), getBestAttachmentState |
attachments.best-attachment, best-attachments; item-summary.best-attachment |
covered |
Attachments.getFileResolvers/getPDFResolvers, addAvailableFile(s), addAvailablePDF(s), canFindFileForItem, downloadFirstAvailableFile, addFileFromURLs |
attachments.find-available-files, get-find-job, cancel-find-job |
partial: Zinc has one fixed resolver chain (Unpaywall, Europe PMC, institution). A plugin cannot add a resolver |
Attachment file write by plugin (OS.File.writeAtomic on the storage path, used by PDF tools) |
attachments.replace-file |
covered |
Zotero.launchFile, ZoteroPane.showAttachmentInFilesystem |
attachments.open-file-external, reveal-file |
covered |
Attachments.isPDFJSDocument/isPDFJSBrowser, linkModeToName/FromName |
link-mode enum |
covered |
Item.setAttachmentLastPageIndex, reader view state file |
attachments.get-view-state, set-view-state |
covered (the stored copy of the JSON that reader.reader-state.primary-view-state holds while a reader is open; the reader owns the format) |
Full text (fulltext.js)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.Fulltext.getIndexedState/isFullyIndexed/getPages, getIndexStats |
fulltext.get-index-state |
partial: no page counts, no stats. Needs core |
Read .zotero-ft-cache / indexed content |
fulltext.get-content |
covered |
Fulltext.setItemContent, custom indexing by plugins |
fulltext.set-content |
partial. Needs core: fulltext.source accepts only zotero-cache and document-worker; add plugin |
Fulltext.indexItems, indexDocument/indexPDF/indexEPUB, rebuildIndex, reindexTruncated, queueItem |
fulltext.reindex |
partial. Needs core: no reindex route |
Fulltext.findItemsWithContent, findTextInItems, getContentSearchSQL |
fulltext.search; fulltextContent search condition |
partial: FTS5 (stemmed) rather than Zotero’s word index; results differ. Since Zotero 10 Zotero also uses FTS5 (an attached ftindex database, fulltextWords tables dropped, fulltextWord condition removed, fulltextContent kept), so word-index SQL in a ported plugin has no equivalent in either: use fulltext.search |
Fulltext.getAttachmentIndexQueueCount, processAttachmentIndexQueue, etc. |
fulltext.get-queue-status |
partial: counts only |
Fulltext.canIndex, getItemCacheFile, semanticSplitter, converter paths, sync content (getUnsyncedContent, processSyncedContent, registerSyncContentProcessor), clearItemWords, vacuum, optimizeContentIndex |
n/a | not planned: Zotero’s own index internals and its full-text sync. Zinc uses SQLite FTS5 |
Raw database (db.js)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.DB.queryAsync/valueQueryAsync/rowQueryAsync/columnQueryAsync/queryTx (read) |
library.query-items, query-keys, count-items, facets, list-tags |
not planned for raw SQL; see design note 3. Common read cases covered by the query interface |
Zotero.DB.queryAsync writes (UPDATE/INSERT/DELETE), executeSQLFile |
library.apply |
not planned for raw SQL writes. Writing around the data layer breaks the sync outbox triggers, the FTS and quick-search indexes and migrations |
Zotero.DB.executeTransaction, inTransaction, requireTransaction, waitForTransaction, Zotero.DB.transactionTimestamp |
library.apply (one atomic batch) |
covered. No interactive transactions: a transaction cannot span calls, so one cannot hold the write lock across a process boundary |
Zotero.DB.tableExists/columnExists/indexExists/getColumns, vacuum, backupDatabase, integrityCheck, addCallback, observe, loadExtension, corruption handlers, closeDatabase |
n/a | not planned: Zotero schema and storage engine specifics |
Zotero.DataDirectory paths for the database |
n/a | not planned: a plugin must not name library files; also unsafe |
Notifier (notifier.js)
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.Notifier.registerObserver(ref, types, id, priority) |
notifier.subscribe(subscription) + export notifier-handler.on-events |
partial. Needs core: no change feed. Today only this layer’s own writes are seen (see notes). Decided 2026-11-18: the core gets a change log in phase 2 |
ref.notify(event, type, ids, extraData) |
event record: object, kind, ids, extra |
covered |
unregisterObserver(id) |
notifier.unsubscribe |
covered |
| Types: collection, search, item, file, collection-item, item-tag, tag, group, trash, relation, setting, sync, share, share-items, bucket, api-key, feed, feedItem | object-type enum |
covered as names. Events fire only for data Zinc has: no share, share-items, bucket, api-key, feed, feed-item events (no such features): partial |
UI types tab, itemtree, itempane, infobox |
none in object-type. Tab changes (with selection, view and theme changes) arrive once, from extend.subscribe-events; the other three are internal refresh signals |
partial: tab events are in extend; itemtree, itempane, infobox are not planned |
| Events add, modify, delete, move, remove, refresh, redraw, trash, restore, index | event-kind |
covered. unreadCountUpdated, pageChange (file) and open (file) belong to feeds / reader: not planned for feeds, reader area for the rest |
Transaction merging, Notifier.begin/commit/queue, skipNotifier, skipSelect, skipAutoSync |
batches merge per apply / flush; apply-options.skip-notify; event.options |
partial: skipSelect is UI; plugins cannot open notifier transactions (begin/commit not planned) |
| Priority ordering of observers | subscription.priority |
covered |
Notifier.trigger by plugins (custom events) |
notifier.trigger for other and UI types only |
partial: by design a plugin cannot forge item events |
Notifier.getLeakedObserverIDs |
n/a | not planned: window leak debugging |
Cite, Quick Copy, Translate, Sync, utilities
| Zotero capability | Zinc WIT | Status |
|---|---|---|
Zotero.Styles.getAll/getVisible/get, Zotero.Style.getXML |
cite.list-styles, get-style-xml |
covered |
Zotero.Styles.install, Style.remove |
cite.install-style, remove-style |
partial: install by repository id only; no install from XML text (core installs from zotero.org; add install-style-xml) |
Zotero.Cite.makeFormattedBibliographyOrCitationList, Zotero.QuickCopy.getFormattedNameFromSetting, Style.getCiteProc() |
cite.format |
partial: output html / text / rtf / note citation markup (note-citation, for note-editor.insert-html), locator, prefix, suffix, suppress-author supported; a plugin cannot get the citeproc engine object, nor use footnote or integration callbacks |
Zotero.QuickCopy.getContentFromItems, getNoteFormat, getFormatFromURL, annotationsToNote, site settings |
cite.quick-copy, get-quick-copy-settings |
partial: no per-site format rules, no export-translator Quick Copy format, no annotation to note. Needs core |
Zotero.Cite.System (retrieveItem, getAbbreviation), Zotero.Cite.getLocatorString |
n/a | not planned: citeproc engine glue. Plugin can ship its own citeproc and feed it CSL JSON from data-utils.item-to-csl-json |
Zotero.Translators.getAllForType/get/getWebTranslatorsForLocation/getImportTranslatorsForLocation |
translate.list-translators |
partial: the web translators-for-URL matching is not exposed |
Zotero.Translators.save/load/loadFromFile (install a translator) |
n/a | not planned in phase 1: arbitrary translator JS would run in the core’s translator sandbox, outside the plugin sandbox. Open question 5 |
Zotero.Translate.Import (setString, setTranslator, translate) |
translate.import-text |
covered |
Zotero.Translate.Export |
translate.export-items |
covered (text output only; binary output formats are not returned: partial) |
Zotero.Translate.Search (lookup by identifier) |
translate.lookup |
covered for DOI, PMID, PMCID, arXiv, ISBN (what Zinc’s lookup resolves); other search translators: partial |
Zotero.Translate.Web, HiddenBrowser, Zotero.Translate.ItemSaver, translator callbacks (setHandler, select) |
translate.web, web-select |
partial: choose-then-select flow only. No DOM Document hand-over, no custom item saver or handlers |
Zotero.Sync.Runner.sync(), Runner.running, Sync.Runner.addListener |
sync-control.sync-now, get-state; notifier type sync |
covered |
Zotero.Sync.Data, Sync.Storage, Sync.Server, Zotero.SyncedSettings |
n/a | not planned: sync engine internals. Plugin data syncs through item JSON relations or extra, or not at all |
Zotero.Date.strToDate, strToISO, sqlToDate, dateToSQL, multipartToStr, getLocaleDateOrder |
data-utils.parse-date, to-iso-date, display-date |
partial: the three common ones; SQL date helpers are pure and a plugin can use its own date library. Locale date order: ui/lifecycle l10n |
Zotero.Utilities.Item.itemToCSLJSON, itemFromCSLJSON |
data-utils.item-to-csl-json, item-from-csl-json |
covered (item-from-csl-json needs core: no CSL to item mapper outside import) |
Zotero.Utilities.extractIdentifiers, cleanDOI, cleanISBN, isDOI |
data-utils.extract-identifiers |
covered for extraction. Cleaning is guest-side |
Zotero.Utilities string, HTML and XML helpers (trim, cleanTags, capitalizeTitle, xpath, parseURL) |
n/a | not planned: generic code; ship it in the plugin |
Feeds: Zotero.Feeds, FeedItems, Feed, FeedReader |
n/a | not planned: Zinc has no RSS feeds feature. A plugin can fetch a feed with the lifecycle’s network permission and create items with apply |
Zotero.Retractions, Zotero.Report, Zotero.Timeline |
n/a | not planned: retraction checks and reports are features of Zotero itself; plugins read the retracted search condition when it exists (needs core) |
Counts (rows in the tables above, counted by script): covered 69, partial 39, not planned 25.
2. Design notes
- One write call,
library.apply. Zotero writes withitem.saveTx(),Zotero.DB.executeTransaction(async () => {...})and many small awaits. Each await would be a process crossing, and an interactive transaction (read, decide, write while holding the lock) would let a stuck plugin hold the library write lock. Instead a plugin sends a list ofchanges and the core runs them in one SQLite transaction in order, all or nothing, and answers with the new keys.new-keyslets a plugin link objects it creates in the same batch (parent and child, collection and member) without a round trip. Conflicts use optimistic concurrency (expected-modified) in place ofhasChanged. Failure reports the change index. - Items are JSON, lists are cheap. Item data travels as Zotero Web API item JSON because the core stores it that way (
items.data) and every guest language has a JSON parser; the open-ended field set needs no WIT change when Zotero adds fields. Lists useitem-summaryrecords with opt-infieldsandexpandflags, so item tables do not cost a call per row.get-itemstakes many keys, andget-summaries(keys, fields, expand)returns the cheap summary form with a field list for many keys (the call the extend area’s custom columns, menu contexts and row styles use after they receive item keys). There is no object with setters and no handle, so there is nothing to keep alive across the boundary and nothing to leak. - Raw SQL: not planned. Reasons: Zinc’s tables are not Zotero’s (no
itemData,itemDataValues,itemAttachments; items are JSON);core/schema.sqlchanges through migrations that plugins would break; writes would bypass the sync outbox triggers and the FTS5 and quick-search indexes; readingdataJSON in SQL ties plugins to storage details. What covers the common plugin SQL: finding items by field value or date (query-itemswith conditions); counts by tag, type, year, creator (facets,list-tags); membership (get-collection-items); full-text hits (fulltext.search); relations (find-by-relation). Open question 1 proposes a read-only view schema for later. - Notifier delivery.
subscribeis a host import; delivery is the exportedon-events(subscription, batch). The host coalesces events (default 50 ms window, max 1 s) and merges ids per(object, kind)as Zotero does when it commits a transaction, so a 5,000-item import is a few calls, not 5,000. One batch is in flight per subscription; the queue is bounded (256), and overflow turns into arefreshevent so a plugin re-reads instead of trusting a stream with holes.originis new and lets a plugin ignore its own writes; Zotero code uses ad-hoc flags for that.on-eventsreturns nothing, so the host never waits on plugin code and a slow plugin only slows itself. A plugin that needs a full rescan after downtime usesrefreshplus its own stored “last seen” marker (storage is a lifecycle matter). - What the notifier sees today. The old compat layer saw only changes made through itself and the UI. The core has a
sync_outboxfed by triggers, but those are suppressed while sync applies remote changes and rows are de-duplicated, so they are not a change feed. Phase 2 needs a core change log: a table fed by unsuppressed triggers withseq, object type, key, kind,originand library, plus an HTTP or in-process stream. SQLitedata_version(already used by/api/ui/selection) can detect changes by other processes and produce arefresh. - Permissions. Declared in the manifest, enforced per call; the proposed ids are
library.read,library.write,library.trash(move to trash, restore),library.erase(permanent delete, empty trash, delete a collection or saved search),library.files.read(file bytes),library.files.write(import, replace, rename, delete files, Find Full Text),library.files.paths(see or give absolute paths; also needed forlink-fileandrelink-file),library.files.open(reveal, open externally),library.fulltext.read,library.fulltext.write,library.cite,library.cite.styles,library.translate,library.sync.import-from-urlandtranslate.webneed the lifecycle network permission for the target host. A plugin gets no notifier event for objects it could not read. The default install prompt should group them: read-only, edit library, files, dangerous (erase). - File access without a file system. Bytes cross the boundary, not paths. Reads are chunked (8 MiB per call, 64 MiB whole-file cap), writes take bytes up to 64 MiB or stream through the
file-writerresource, the oneresourcehere, because a partly written upload needs a handle with a lifetime. Absolute paths are hidden unlesslibrary.files.pathsis granted, since paths contain the user’s name and a plugin could otherwise recover it. - Rust and JS ergonomics. Plain records, variants and lists; no callbacks except
on-events.option<option<collection-key>>incollection-update.parentis the one awkward type; it gives “unchanged” versus “move to top level” and could become avariantin a later revision. Names avoid WIT keywords (include,from,import,export,typewere renamed:expand,old-name,importer,exporter,object). - Keys, not IDs. Zotero plugins use numeric
itemID. Zinc has no numeric item id, and keys are unique across libraries. Plugin code written for Zotero that storesitemIDmust store keys. - No object model for search.
Zotero.Searchis a stateful builder. Here a search is asearch-definitionvalue, used inline initem-queryor saved withcreate-saved-search. The condition name set is Zotero’s, so documented plugin searches port; the host answersinvalid-argumentfor conditions it cannot compile.
3. Open questions for the user
- Offer a read-only SQL interface later over a stable view schema (
items,fields,creators,tags,collections), for plugins that need ad-hoc analytics? It would be versioned and independent of the real tables. Phase 1 says no. - Should permissions be scoped to a library (My Library only, or chosen groups), or to a collection? The WIT takes
libraryarguments everywhere, so the host can enforce either. - Should
erase(permanent delete) be allowed to plugins at all, or only trash? Zotero plugins can erase. Proposal: allowed behindlibrary.erasewith a visible prompt. - Add
duplicate-item,move-item-to-library, andconvert-to-stored-fileas first-classchangevariants? They exist in Zotero and the core has duplicate already. - Translators: run a plugin-supplied translator (JS) in the core’s translator sandbox, or only existing ones? The second is what the WIT offers.
- Cap values (query page 1000, file read 8 MiB, upload 64 MiB, event queue 256) are guesses; confirm.
- Should plugin writes mark
dateModifiedas a plugin change in a way the sync layer can show to the user (an audit trail of what each plugin changed)?
4. Needs from other areas
Resolved in the reconcile of 2026-11-18 (see README): world.wit imports and exports every interface of this file; types.wit has item-ref and the one color; the permission ids of design note 6 are in the manifest schema; the notifier no longer has tab, itemtree, itempane, infobox; the view state JSON has one owner (reader), with attachments.get-view-state as its stored copy; get-summaries was added for extend; cite.format has the note-citation output for reader; annotation items go through annotations only; fulltext.get-content (whole document, indexed) and reader.get-page-text (pages of an open reader) both stay.
Still open:
- lifecycle (prefs): the attachment rename template, auto-rename setting and Quick Copy settings are Zotero prefs;
prefs.get-appshould let a plugin read them (extensions.zotero.autoRenameFiles,export.quickCopy.setting). Part of the app prefs allowlist question. - reader: file-open events (Zotero’s
filenotifier type,open,pageChange) come fromreader.subscribe(opened,page-changed), not from the notifier. Relations on annotations (reader.md row 81) are not served bylibrary.find-by-relation: open, needs a decision with the reader area. - ui: item and collection icons, emoji tags, and “select this item” (
ZoteroPane.selectItem) areextend.select-items; item and collection icons and emoji tags have no call yet. Open. - Core features missing (phase 2): change log and event stream; atomic batch route (
POST /api/batch); relation index and collection relations; collection trash;lastRead; charset andsource = pluginfor full text; reindex route; search compiler coverage (groups, number fields,lastRead, annotation conditions,retracted); schema flags; publications write; item duplicate and library move in the batch.