Experimental surfaces

Experimental — public-experimental

The surfaces below are wired and runtime-backed but unproven (no proving test of that surface). They may change or break without a major version bump and carry no compatibility promise. They are not part of the shipped set. Use at your own risk; prefer the shipped surfaces for anything you depend on.

This page collects the surfaces that are reachable today but carry an explicit experimental label. They are documented so you can find them, not because they are safe to depend on.

Authoring note: the documentation source organizes these under a reference/_experimental/ grouping. Because the site build excludes underscore-prefixed paths from routing, the rendered page lives at reference/experimental-surfaces; the grouping intent is unchanged.

version

api.version // string, e.g. '1.0.0' — the API contract version

The contract version is exposed on the root object and is decoupled from the plugin’s release version. It is a lift-ready candidate but is kept experimental until a proving test exists. Read it for information; do not gate critical logic on it yet.

connect() capability-scoping behavior

The connect() handle is shipped, but its capability-scoping behavior is experimental — there is no proven enforcement of scoping at the API level, and scoping is opt-in self-restriction rather than a default control. See Capabilities and permissions for the honest framing.

state.* reactive stores

api.state.library     // Readable<LibraryState>
api.state.highlights  // Readable<HighlightState>
api.state.bookmarks   // Readable<BookmarkState>

Read-only reactive stores backed by real services, but without a proving test. Subscribe for information; expect shape changes.

commands.library / commands.highlights / commands.bookmarks

Real service-backed command facades that are wired but unproven:

• commands.library — book queries, search, filtering, scan, and query helpers.
• commands.highlights — highlight CRUD, search, and count. This facade emits the highlight-* events, which inherit this experimental tier (see the per-event table).
• commands.bookmarks — bookmark CRUD, toggle, has-at, and count.

hooks — vetoable middleware

hooks.register(name, fn)   // → Disposable
// executeHook(...) → Promise<boolean>

A vetoable middleware mechanism that can transform or block an action — strictly more powerful, and more dangerous, than notify-only events. Its only consumer today is a scaffolded surface, it is performance-sensitive (a slow hook can stall rendering), and it is unproven. Experimental.

'amnesia:ready' handshake

this.app.workspace.on('amnesia:ready', ({ api, version }) => {
  // the API is available
});

A one-shot workspace event fired on plugin load carrying { api, version }. It has a real consumer but no test, so it is experimental. As a shipped alternative, read this.app.plugins.plugins['amnesia']?.api directly (see Access the API).

Related

• Access the API
• Events
• Capabilities and permissions

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