---
title: "commands.mupdf"
description: "Shipped MuPDF facade — extract text, snap and copy selections, annotate, extract regions, and read page geometry. Async and capability-gated."
canonical: https://amnesia-docs.pages.dev/api/reference/commands-mupdf/
source: "src/content/docs/api/reference/commands-mupdf.md"
---

# commands.mupdf

:::tip[Shipped — public-stable]
`commands.mupdf` is part of the first-release shipped surface: wired and proven.
:::

:::caution[Highest performance-risk surface]
`commands.mupdf` exposes the document renderer. Every method is **asynchronous and capability-gated**,
and the facade **never hands you the shared MuPDF bridge object** — only these methods. Always `await`
calls and avoid tight loops that could stall paint. Treat document rendering as **desktop-first**.
:::

The MuPDF facade reads and annotates the open PDF document.

```js
const api = window.Amnesia; // or this.app.plugins.plugins['amnesia']?.api
const text = await api.commands.mupdf.extractPageText(1);
```

## Methods

| Method | Purpose | Capability |
| --- | --- | --- |
| `extractPageText(page)` | Extract text from a page; resolves to a text-extraction result. | `read-document` |
| `extractRegion(region)` | Extract text/content for a region of the page. | `read-document` |
| `snapSelection(selection)` | Snap a raw selection to document geometry. | `read-document` |
| `copySelection(selection)` | Produce a copyable representation of a selection. | `read-document` |
| `highlightSelection(selection)` | Create a highlight from a selection. | `write-annotations` |
| `createAnnotation(annotation)` | Create a PDF annotation; resolves to the created `PDFAnnotation`. | `write-annotations` |
| `getAnnotations(page)` | List annotations on a page. | `read-document` |
| `deleteAnnotation(id)` | Delete an annotation by id. | `write-annotations` |
| `getPageCount()` | Resolve the document's page count. | `read-document` |
| `getPageDimensions(page)` | Resolve a page's dimensions. | `read-document` |
| `search(query)` | Search the document; resolves to matches. | `read-document` |

Method names are exact. Geometry and annotation payloads use the MuPDF types (`PDFPoint`, `PDFBounds`,
`TextExtractionResult`, `PDFAnnotation`, `PDFSelectionMode`) from the API type definitions.

## Behavior notes

- **Async-only.** Every method returns a `Promise`; the async boundary lets the engine throttle or
  offload rendering work.
- **Capability-gated.** Read primitives require `read-document`; annotation writes require
  `write-annotations`. A gated call on an under-scoped [`connect()`](/api/reference/access/) handle throws
  [`PermissionError`](/api/reference/capabilities/#permissionerror). The `PermissionError` at the facade
  is shipped and proven; the
  [`connect()` capability-scoping](/api/reference/experimental-surfaces/#connect-capability-scoping-behavior)
  that makes a handle under-scoped is itself experimental and untested.
- **No raw bridge.** The shared rendering bridge is never returned. Build on these methods only.
- **Platform.** The rendering path depends on native components; probe availability and degrade
  gracefully rather than assuming it on mobile.

## Related

- Guide: [Extract and annotate PDFs with MuPDF](/api/guides/render-with-mupdf/)
- [Capabilities and permissions](/api/reference/capabilities/)

<sub>Reference verified as of 2026-06-28.</sub>