Plugin system
ReadAware plugins compose capabilities the desktop host exposes. They can work with books, reading state, annotations, conversations, and memory; add actions and providers; and use bounded host services.
This reference follows the development source. Match capability requirements to your installed app before building or publishing.
Choose a capability family
| Family | Use it for | Examples |
|---|---|---|
| Domains | ReadAware-owned data and behavior | Library, reading, annotations, conversations, settings, memory |
| Contributions | New actions, choices, or provider implementations | Commands, context actions, voices, content sources, assistant tools, themes |
| Services | Host operations and plugin-private facilities | Resources, network, inference, storage, schedules, jobs, transactions |
| Schemas | Data the host renders or interprets | Views, settings forms, themes |
Use the Capabilities Explorer to search actual methods, understand boundaries, and start a manifest. The API reference explains how the families compose.
Start from the reader's task
- Find and navigate: use Library source search and range reads, then Reading navigation with the current session guard.
- Collect and review notes: query or observe Annotations; conditional mutations preserve newer edits.
- Work with reading memory: use Memory queries and authorized commands for memories, classification, profiles, entities, graphs, and context bundles.
- Assist a conversation: read authorized transcripts and summaries, propose a turn for host approval, or register an assistant tool.
- Automate a workflow: combine schedules, scoped change cursors, supported durable jobs, and local transactions.
- Bring in outside content: use origin-scoped network access, content providers, and sealed resources instead of filesystem or browser escape hatches.
Permissions, versions, and object grants
These are separate checks:
requiresdeclares compatible capability versions.permissions,settingsAccess, andnetworkAccessdeclare authority.- The user's book grant limits the actor to all books, the current book, or a specified book.
- Lifecycle and current runtime conditions determine whether a particular operation is available now.
A permission-free service can still require another domain grant for a specific method. A successful availability query is a hint, not permission to bypass the execution check.
Host-rendered interfaces
Plugins return structured views and callbacks. ReadAware owns rendering, focus, navigation, loading and error states, themes, and cleanup. Views can include lists, forms, detail layouts, and bounded blocks, with live updates through the public view contract.
Plugins do not mount React, arbitrary HTML, CSS, iframes, or a DOM. Use a supported contribution point for new UI behavior.
Isolation and lifecycle
Each plugin runs in a module Worker. It receives no direct Tauri, SQLite, filesystem, process, or DOM access. Network and storage use the host-mediated context.
Activation stages registrations and permits supported reads; business writes and external side effects begin from active handlers. A private-data migration runs with storage-only authority. Failed activation or migration is rolled back before a candidate replaces the current runtime.
Marketplace plugins update automatically when a new release asks for no authority beyond what the user approved — permissions, settings access and network origins; anything more waits for consent. Plugins installed from a folder or zip are never replaced by a marketplace listing.
Installation is still a software trust decision. Review the package source, requested authority, network destinations, and data handling.
Learn from first-party plugins
The source tree contains working examples such as Jumper, Dictionary, and Sentence Reader, alongside bundled plugins. Source examples are not a promise that every package ships in every release.