mktero AGENTS.md

AGENTS.md

This file applies to the entire repository.

Project overview

Mktero is a restartless Zotero extension for Zotero 7 through 10. It reads a local PDF attachment, sends the PDF to MinerU, and opens the returned Markdown and images in a read-only Zotero tab.

The project is plain JavaScript, not TypeScript. Source files use ES modules, while esbuild bundles the two runtime entry points as browser IIFEs for Firefox 115. Zotero supplies the privileged runtime globals used by the extension, including Zotero, IOUtils, PathUtils, Components, ChromeUtils, and Services.

Commands

Use the Node.js version in .node-version (currently 24.15.0); it is the shared local and CI version source. Do not use Node.js 25, which is outside the supported dependency engine range.

npm ci
npm run check
npm test
npm run build

• Run one test file with node --test test/<name>.test.js while iterating.
• npm run check syntax-checks every source module explicitly. Add new source files to the check script in package.json.
• npm run build recreates build/package, the reproducible build/mktero-<version>.xpi, its .sha256 checksum, and build/updates.json. Both build/ and node_modules/ are generated and ignored; never edit or commit them.
• scripts/build.mjs has an explicit list of copied runtime assets. Update it when adding a non-imported file required by the packaged extension.

Before handing off a change, run the narrow tests for the touched behavior, then npm run check, npm test, and npm run build unless the change is documentation-only. Report any command that could not be run.

Repository map

• manifest.json: Zotero compatibility, extension ID, version, and update URL.
• prefs.js: defaults for every Zotero preference.
• src/bootstrap.js: extension lifecycle and dependency composition. It owns startup/shutdown, conversion cancellation, tabs, toolbar actions, context menus, preferences, and cache.
• src/config/: preference keys and preference-pane registration.
• src/core/: provider-independent conversion orchestration and progress.
• src/extractors/: adapters from Zotero items or MinerU results to the core document shape.
• src/mineru/: MinerU API client, parsing profile, ZIP extraction, binary helpers, and Markdown normalization.
• src/cache/: content-addressed Markdown and image cache under the active Zotero profile.
• src/platform/: Zotero/runtime adapters for aborting requests.
• src/markdown/: pure Markdown parsing, analysis, normalization, rendering, and safety logic.
• src/editor/: CodeMirror 6 read-only presentation, image previews, and citation/table/figure interactions.
• src/ui/: Zotero toolbar, item menu, tab presenter/view, loading state, and preference controller.
• ui/: packaged XHTML, CSS, and icons.
• test/: Node test runner coverage, with jsdom or linkedom where DOM behavior is needed.