mktero: Instructions file for Codex

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 it to the selected OCR provider (MinerU or Mistral OCR) when needed, and opens the resulting Markdown, figures, citations, annotations, and optional AI translation in a session-only, reading-first Zotero tab.

The project is plain JavaScript, not TypeScript. Source files use ES modules, while esbuild bundles the runtime entry points as browser IIFEs for Firefox 115 (the bootstrap, the preferences UI, and the figure render worker), plus the bundled pdf.js worker. 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/ai/: Vercel AI SDK gateway, translation service, and request tracking.
• src/cache/: content-addressed Markdown, figure, translation, citation-graph, and reading-position stores under the active Zotero profile.
• src/citations/: citation-graph building and the Semantic Scholar, OpenCitations, and OpenAlex clients.
• src/config/: preference keys, preference-pane registration, and the session-only models.dev reasoning catalog used by the AI reasoning menu.
• src/core/: provider-independent conversion orchestration and progress.
• src/extractors/: adapters from Zotero items or provider results to the core document shape.
• src/figures/: figure region resolution, panel/label recovery, reading-order reunion, and the worker-based restoration pipeline.
• src/i18n/: English and Simplified Chinese user-facing copy.
• src/icons/: bundled lucide icon helpers.
• src/mineru/: MinerU API client, parsing profile, ZIP extraction, binary helpers, and the raw result archive.
• src/mineru/document/: the MinerU reading document. It ingests layout.json (or the content list) into a block IR, classifies page chrome, repairs reading order, stitches paragraphs across pages, columns and floats, and serializes Markdown with its exact source map and figure-pipeline input.
• src/mistral/: Mistral OCR client, parsing profile, and result normalization.
• src/pdf/: PDF.js text engine, page crops, annotation location, and outlines.
• src/platform/: Zotero/runtime adapters for aborting requests and Zotero APIs.
• src/markdown/: pure Markdown parsing, analysis, normalization, rendering, and safety logic.
• src/editor/: CodeMirror 6 presentation, inline correction editing, 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.
• docs/: README-linked user documentation. The directory is gitignored except for an explicit allowlist in .gitignore; see the cross-file checklist.
• preview/: browser preview of the reader for the website and browser compatibility checks (npm run build:preview). Fixture data only; not part of the XPI. See docs/development.md.
• scripts/: build, figure validation harnesses, the figure-corpus check, and the browser preview build, packaging, and validation.
• test/: Node test runner coverage, with jsdom or linkedom where DOM behavior is needed.