Extract and annotate PDFs with MuPDF

This guide covers the shipped commands.mupdf facade — the document primitives for reading and annotating PDFs.

Async, capability-gated, no raw bridge

Every MuPDF method is asynchronous and capability-gated, and the facade never returns the shared rendering bridge. Always await, avoid tight loops that could stall paint, and treat document rendering as desktop-first — probe availability and degrade gracefully.

1. Read the document

const api = window.Amnesia; // or this.app.plugins.plugins['amnesia']?.api

const pages = await api.commands.mupdf.getPageCount();
const text = await api.commands.mupdf.extractPageText(1);
const dims = await api.commands.mupdf.getPageDimensions(1);

2. Work with selections and regions

const snapped = await api.commands.mupdf.snapSelection(selection);
const copied = await api.commands.mupdf.copySelection(selection);
const region = await api.commands.mupdf.extractRegion(/* { page, bounds } */);

3. Search

const matches = await api.commands.mupdf.search('mitochondria');

4. Annotate (requires write-annotations)

const highlight = await api.commands.mupdf.highlightSelection(selection);
const annotation = await api.commands.mupdf.createAnnotation(/* annotation payload */);
const onPage = await api.commands.mupdf.getAnnotations(1);
await api.commands.mupdf.deleteAnnotation(annotation.id);

Capabilities

Read primitives (extractPageText, extractRegion, snapSelection, copySelection, getAnnotations, getPageCount, getPageDimensions, search) require read-document. Annotation writes (highlightSelection, createAnnotation, deleteAnnotation) require write-annotations. On an under-scoped connect() handle, a gated call throws PermissionError. The facade-level PermissionError is shipped and proven; the connect() capability-scoping that makes a handle under-scoped is itself experimental and untested.

Performance

Because this surface drives the renderer, keep calls off hot paths, batch where you can, and never block on synchronous work — the async contract exists so the engine can throttle or offload rendering.

_{Reference verified as of 2026-06-28.}