Events

Shipped — public-stable (mechanism only)

The .events delivery mechanism (on / off / once) is part of the first-release shipped surface. Individual event readiness is labeled per event — see the per-event readiness table. Subscribing to an event that does not fire is safe, but your handler simply never runs.

The events facade is a typed, notify-only subscription mechanism over a fixed event map. Subscribing returns a Disposable you can use to unsubscribe.

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

const sub = api.events.on('note-created', (payload) => {
  // react to the new note
});

// later — clean up:
sub.dispose();

Methods

Method	Purpose	Returns
on(eventName, handler)	Subscribe to an event for every emission.	Disposable
once(eventName, handler)	Subscribe for a single emission, then auto-unsubscribe.	Disposable
off(eventName, handler)	Unsubscribe a previously registered handler.	void

Event names are typed against the reader event map; on/once return a Disposable.

Clean up with Disposable

Every subscription returns a Disposable with a dispose() method. Always dispose your subscriptions on unload to avoid leaked listeners — the most common cause of plugin instability:

// In a plugin, tie the subscription to the plugin lifecycle:
const sub = api.events.on('link-created', onLink);
this.register(() => sub.dispose());

Per-event readiness

The mechanism is shipped, but whether a given event fires depends on the facade that emits it, and those facades are at different readiness tiers. Each event class is labeled individually:

Event class	Members	Readiness	Notes
Notes / links	note-*, link-*	Shipped	Fire today; emitted by the shipped notes/links facades.
Highlights	highlight-created, highlight-updated, highlight-deleted	Experimental	Emit at runtime, but the emitting facade is experimental and unproven. Do not treat as shipped.
Reader / content / navigation	relocated, page-turn, rendered, text-selected, …	Not available	Do not fire today — they depend on the scaffolded reader bridge.
Collection	collection-*	Not available	Emitted only by an unwired bridge; untyped (not in the reader event map).

Subscribing to a not-available event is harmless but useless until the underlying surface is wired.

Related

• Guide: Subscribe to events
• commands.notes and commands.links (emit the shipped events)
• Experimental surfaces (the highlights facade that emits the experimental highlight events)

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