---
title: "Experimental surfaces"
description: "Surfaces that are wired and runtime-backed but unproven. They carry an explicit experimental label, may change or break without notice, and are not part of the shipped set."
canonical: https://amnesia-docs.pages.dev/api/reference/experimental-surfaces/
source: "src/content/docs/api/reference/experimental-surfaces.md"
---

# Experimental surfaces

:::caution[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](/api/overview/#what-ships-in-the-first-release). 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`

```ts
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()`](/api/reference/access/#connect--a-scoped-audited-handle) **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](/api/reference/capabilities/) for the honest framing.

## `state.*` reactive stores

```ts
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](/api/reference/events/#per-event-readiness)).
- `commands.bookmarks` — bookmark CRUD, toggle, has-at, and count.

## `hooks` — vetoable middleware

```ts
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

```js
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](/api/reference/access/)).

## Related

- [Access the API](/api/reference/access/)
- [Events](/api/reference/events/#per-event-readiness)
- [Capabilities and permissions](/api/reference/capabilities/)

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