@muninmd/munin-sdk 0.0.0-stage → 1.1.0

package/plugin-api.d.ts

@@ -0,0 +1,779 @@
+import type * as CMState from '@codemirror/state'
+import type * as CMView from '@codemirror/view'
+import type { Permission, PluginPlatform } from './plugin-package.js'
+/**
+ * The plugin API, version 1 — the one surface the app supports for plugins.
+ *
+ * A plugin's entry file is an ES module whose default export is a function of
+ * this shape; the app calls it with a {@link PluginContext} when the person
+ * switches the plugin on:
+ *
+ * ```js
+ * export default function activate(ctx) {
+ *   ctx.commands.register({ id: 'hello', title: 'Say hello', run: () => ctx.ui.notice('Hello') })
+ * }
+ * export function deactivate() {}   // optional
+ * ```
+ *
+ * Everything the plugin registers goes through `ctx`, is stamped with the
+ * plugin's id as its owner, and is taken back when the plugin is switched off —
+ * so a plugin that uses only this file leaves nothing behind. Anything it
+ * reaches by another road (`window`, the DOM, `window.api`) is its own risk and
+ * may change without notice.
+ *
+ * This file is also the source of the declaration file given to authors
+ * (`plugins/sdk/plugin-api.d.ts`), so it imports nothing from the app.
+ */
+/** Undoes one registration. Calling it twice is harmless. */
+export type Disposer = () => void
+export declare const PLUGIN_API_VERSION = 1
+export interface PluginCommand {
+  /** Short id, unique within the plugin. The palette shows it under the plugin's
+   *  own name, so two plugins can both have `refresh`. */
+  id: string
+  title: string
+  /** Optional heading to group commands under in the palette. */
+  section?: string
+  run: () => void | Promise<void>
+}
+export interface PluginView {
+  /** Short id, unique within the plugin. */
+  id: string
+  title: string
+  /** An SVG, as a string, for the tool stripe. Drawn with `currentColor`. */
+  icon: string
+  /**
+   * Fill `el` with the panel. Called when the panel opens; return a function to
+   * clean up when it closes. The app owns `el` — it is yours to render into, not
+   * to keep a reference to after the cleanup runs.
+   */
+  mount: (el: HTMLElement, instance: PluginViewInstance) => void | (() => void)
+  /**
+   * How the view opens on a phone. `sheet`: a sheet from a button in the
+   * library, for something glanced at. `page`: the whole screen, from the dock's
+   * menu, for something worked in. Without either the view has no way in on a
+   * phone. On a computer it is an ordinary panel in every case.
+   */
+  mobile?: 'sheet' | 'page'
+  /**
+   * The panel can be expanded over the whole workspace. The app then puts a
+   * control for it in the panel's header — one look and one Escape key for every
+   * plugin — and puts the arrangement back afterwards. Expanding is never saved: a
+   * restart shows the normal layout. Opening a note, or anything else that moves
+   * the person's attention, collapses it by itself.
+   *
+   * Only on a computer. On a phone a `page` already fills the screen.
+   */
+  expandable?: boolean
+}
+/**
+ * One open panel of a view. Two panels of the same view are two instances, and
+ * each keeps its own state: on a computer it is saved with the layout and comes
+ * back with it, on a phone it lasts while the sheet or page is open. The state
+ * must survive `JSON.stringify`; anything that does not is dropped.
+ */
+export interface PluginViewInstance {
+  state<T = unknown>(): T | undefined
+  setState(value: unknown): void
+  /**
+   * Whether the panel fills the workspace right now. On a phone, true for a
+   * `page` and false for a `sheet`.
+   */
+  expanded(): boolean
+  /**
+   * Expand or collapse the panel, as its header control does. Does nothing — and
+   * warns in the plugin's log — for a view that did not declare `expandable`, and
+   * does nothing on a phone.
+   */
+  setExpanded(on: boolean): void
+  /**
+   * Told when the panel is expanded or collapsed, after it has its new size, so a
+   * measurement taken in the callback is the new one. Use it to change *what* is
+   * drawn (labels shown only when there is room); how big it is, a
+   * `ResizeObserver` reports as it does for any resize. Returns what stops the
+   * calls; whatever is left is dropped when the panel closes.
+   */
+  onExpandedChange(callback: (expanded: boolean) => void): Disposer
+}
+interface FieldBase {
+  /** Short id, unique within the section; also the key {@link PluginSettings.get} reads. */
+  id: string
+  label: string
+  hint?: string
+  /**
+   * Where the value is kept. `device` (the default) is this computer; `vault` is
+   * the open vault — a folder name means something only in the vault it names,
+   * and the value follows whichever vault is open.
+   */
+  scope?: 'device' | 'vault'
+}
+export interface ToggleSetting extends FieldBase {
+  kind: 'toggle'
+  default: boolean
+}
+export interface TextSetting extends FieldBase {
+  kind: 'text'
+  default: string
+  /** Why a value is not acceptable, or null when it is. */
+  validate?: (value: string) => string | null
+  /** Ready-made values that fill the field in one gesture. */
+  presets?: {
+    value: string
+    label?: string
+  }[]
+}
+export interface SettingOption {
+  id: string
+  label: string
+}
+export interface ChoiceSetting extends FieldBase {
+  kind: 'choice'
+  default: string
+  /**
+   * The choices — fixed, or worked out when needed. A function is asked again
+   * whenever the vault's notes change, so a list of folders keeps up with the
+   * folders.
+   */
+  options: SettingOption[] | (() => SettingOption[] | Promise<SettingOption[]>)
+}
+/** A button in the settings, for something that is not a value. */
+export interface ActionSetting {
+  kind: 'action'
+  id: string
+  label: string
+  hint?: string
+  run: () => void | Promise<void>
+}
+/**
+ * A value the person types and nobody reads back — an access key, a token. It
+ * is kept as one of the plugin's {@link PluginSecrets} under the field's id, so
+ * `ctx.secrets.get(id)` reads it. The settings show only whether it is set; the
+ * person can type a new one or clear it, never see the old one.
+ *
+ * {@link PluginSettings.get} answers `''` for it, and `onChange` is told `true`
+ * when a value was set and `false` when it was cleared — never the value.
+ */
+export interface SecretSetting {
+  kind: 'secret'
+  /** Short id, unique within the section; also the secret's name. */
+  id: string
+  label: string
+  hint?: string
+  placeholder?: string
+}
+export type SettingField =
+  ToggleSetting | TextSetting | ChoiceSetting | ActionSetting | SecretSetting
+export interface SettingsGroupDef {
+  /** Short id, unique within the section. */
+  id: string
+  /** Heading over the group; leave it out for a single unlabelled group. */
+  label?: string
+  fields: SettingField[]
+}
+export interface SettingsSectionDef {
+  /** Short id, unique within the plugin. */
+  id: string
+  title: string
+  /** The fields, when there is one group of them. */
+  fields?: SettingField[]
+  /** Several groups, each under its own heading. Used instead of `fields`. */
+  groups?: SettingsGroupDef[]
+  /**
+   * Draw the section yourself, for settings that are not a list of values — a
+   * list of connections, say. Used instead of `fields` and `groups`. Called when
+   * the section is shown; return a function to clean up when it is closed. As
+   * with a panel, `el` is the app's: render into it, do not keep it.
+   *
+   * Draw with the app's colours (`var(--text)`, `var(--text2)`, `var(--island)`,
+   * `var(--border-soft)`, `var(--accent)` …) so the section looks like its
+   * neighbours in both themes.
+   */
+  mount?: (el: HTMLElement) => void | (() => void)
+}
+export interface PluginSettings {
+  /** Add a section to the settings, after the built-in ones. */
+  register(section: SettingsSectionDef): Disposer
+  /** The current value of a field, or its default. */
+  get<T extends boolean | string = boolean | string>(fieldId: string): T
+  /** Change a field's value from code — to select the folder a plugin has just
+   *  created, say. Runs the field's change handlers like a change by the person. */
+  set(fieldId: string, value: boolean | string): void
+  /** Called after the person changes a field. */
+  onChange(fieldId: string, handler: (value: boolean | string) => void): Disposer
+  /**
+   * Show the settings at one of this plugin's sections — the first one it
+   * registered when `sectionId` is left out. On a computer the settings window
+   * opens on it; on a phone the plugin's settings page does, and back returns
+   * to where the person was.
+   */
+  open(sectionId?: string): void
+}
+export interface PluginTheme {
+  id: string
+  name: string
+  base: 'dark' | 'light'
+  /** CSS custom properties, e.g. `{ '--canvas': '#242933' }`. */
+  tokens?: Record<string, string>
+}
+/** What the app publishes. Anything else is a plugin's own event, untyped. */
+export interface PluginEvents {
+  'file-open': {
+    path: string
+  }
+  'active-note-change': {
+    path: string | null
+  }
+  'metadata-updated': void
+  'tree-changed': void
+  /** A note or folder appeared, changed, moved or went. `origin` is `app` when
+   *  this app did it (the person, or a plugin), `external` when another program
+   *  or a sync client did. A full reread of the vault gives no per-file event. */
+  'file-created': PluginFileEvent
+  'file-modified': PluginFileEvent
+  /** Renamed or moved; `oldPath` is where it was. */
+  'file-renamed': PluginFileEvent & {
+    oldPath: string
+  }
+  'file-deleted': PluginFileEvent
+}
+export interface PluginFileEvent {
+  path: string
+  /** Whether it is a folder; absent when the app could not tell — something
+   *  another program did that it has not looked at yet. */
+  folder?: boolean
+  origin: 'app' | 'external'
+}
+export interface PluginVault {
+  /** The open note's path (vault-relative, `/`-separated), or null. */
+  activePath(): string | null
+  /** Every note's path. Needs `vault:read`. */
+  list(): Promise<string[]>
+  /** A note's text — from its editor when it is open, unsaved typing
+   *  included. Needs `vault:read`. */
+  read(path: string): Promise<string>
+  /** Replace a note's text, or create it. An open note changes in its editor
+   *  (undoable, saved like typing); any other is written to disk. Needs
+   *  `vault:write`. */
+  write(path: string, text: string): Promise<void>
+  /** Open a note in the active pane. */
+  open(path: string): void
+  /** Every folder in the vault, vault-relative. Needs `vault:read`. */
+  folders(): Promise<string[]>
+  /**
+   * The project a note belongs to, when there is one: in a workspace every
+   * note's path starts with `@<id>/`, the project's; a project opened by itself
+   * holds all of its notes. Null for a plain folder. Needs `vault:read`.
+   */
+  projectOf(path: string): Promise<{
+    id: string
+    name: string
+  } | null>
+  /** Whether a note is there, asked of the disk and not of a list that may lag
+   *  behind it. Needs `vault:read`. */
+  exists(path: string): Promise<boolean>
+  /**
+   * Create a note in `folder` ('' is the vault root) named `name`, with `content`,
+   * and return its path. If the name is taken the note gets the next free one —
+   * so the returned path, not the requested one, is where it is. Needs `vault:write`.
+   */
+  createNote(folder: string, name: string, content?: string): Promise<string>
+  /** Create a folder and return its path. Needs `vault:write`. */
+  createFolder(parent: string, name: string): Promise<string>
+  /**
+   * Rename a note (`newName` without `.md`) or a folder, in place, and return
+   * the new path. Links to it are rewritten and open tabs follow it, as when
+   * the person renames it. Needs `vault:write`.
+   */
+  rename(path: string, newName: string): Promise<string>
+  /** Move a note or folder into `folder` ('' is the root); returns the new
+   *  path. Needs `vault:write`. */
+  move(path: string, folder: string): Promise<string>
+  /** Delete a note or a folder with everything in it. Asks nothing — the person
+   *  agreed to `vault:write` when switching the plugin on. Tabs showing it close. */
+  delete(path: string): Promise<void>
+  /** Any file of the vault as bytes, with its media type. Needs `vault:read`. */
+  readBinary(path: string): Promise<{
+    data: Uint8Array
+    mime: string
+  }>
+  /**
+   * Save a file into the vault's attachments folder, named by the vault's rule
+   * the way a pasted image is; returns its path, ready for `![[…]]`. Needs
+   * `vault:write`.
+   */
+  saveAttachment(name: string, data: Uint8Array): Promise<string>
+  /** What the plugin keeps about the open vault, inside that vault. Unlike
+   *  {@link PluginContext.data}, it differs between vaults and follows the open one. */
+  readonly data: {
+    load<T = unknown>(): Promise<T | undefined>
+    save(value: unknown): Promise<void>
+  }
+}
+/**
+ * A link to a note — `[[link]]` or `[text](path.md)`: what it says, and where in
+ * the text it stands.
+ */
+export interface PluginLink {
+  /**
+   * What it names: for `[[…]]` the name or path inside the brackets without
+   * `#heading` and `|alias` (`projects/plan`); for a markdown link the path as
+   * written, decoded, from the note it is in (`../projects/plan.md`).
+   */
+  target: string
+  /** Offset of the link's first character (`[[`, `[`, or an embed's `!`). */
+  from: number
+  /** Offset just after the link. */
+  to: number
+}
+/** What the index knows about one note. */
+export interface PluginNoteMeta {
+  path: string
+  title: string
+  links: PluginLink[]
+  /** Without the `#`. Both `#inline` tags and frontmatter `tags:`. */
+  tags: string[]
+  aliases: string[]
+  headings: {
+    level: number
+    text: string
+  }[]
+  /** The frontmatter, as scalars and lists of strings. */
+  properties: Record<string, string | string[]>
+}
+export interface PluginBacklink {
+  path: string
+  title: string
+  /** Text around the mention. */
+  snippet: string
+}
+export type PluginResolveResult =
+  | {
+      status: 'ok'
+      path: string
+    }
+  | {
+      status: 'missing'
+    }
+  | {
+      status: 'ambiguous'
+      candidates: string[]
+    }
+  /** `[[id:…]]` names a project that is not open here. */
+  | {
+      status: 'unavailable'
+      project: string
+    }
+export interface PluginGraph {
+  /** `id` is the note's path; `current` marks the note the graph was asked about. */
+  nodes: {
+    id: string
+    title: string
+    current: boolean
+  }[]
+  edges: {
+    source: string
+    target: string
+  }[]
+}
+/**
+ * The app's index of what notes mean — read only. Everything here needs
+ * `vault:read`. The answers come from the same index the app's own panels read,
+ * so they agree with what the person sees; after `metadata-updated` they reflect
+ * the change.
+ */
+export interface PluginMetadata {
+  /** A note's metadata, or null when there is no such note. */
+  note(path: string): Promise<PluginNoteMeta | null>
+  /** The notes linking to `path`. */
+  backlinks(path: string): Promise<PluginBacklink[]>
+  /**
+   * Which note a link's text leads to, by the app's own rules. `from` is the
+   * note the link is written in; in a workspace a bare name is looked for in
+   * its project — without it, in every project.
+   */
+  resolve(target: string, from?: string): Promise<PluginResolveResult>
+  /** The note, the notes it links to and from, and the links among them. */
+  graph(path: string): Promise<PluginGraph>
+  /** Every note and resolved link; `current`, when given, is marked. */
+  vaultGraph(current?: string): Promise<PluginGraph>
+  /** Every tag, with how many notes carry it. */
+  tags(): Promise<
+    {
+      tag: string
+      count: number
+    }[]
+  >
+  notesWithTag(tag: string): Promise<
+    {
+      path: string
+      title: string
+    }[]
+  >
+}
+export interface PluginTemplates {
+  /** The vault's templates. Needs `vault:read`. */
+  list(): {
+    path: string
+    name: string
+  }[]
+  /** A template's text with its variables filled in for a note at `intoPath`.
+   *  Needs `vault:read`. */
+  render(templatePath: string, intoPath: string): Promise<string>
+}
+/** Dates as this app reads and writes them. */
+export interface PluginDates {
+  /** Tokens `YYYY MM DD dddd LL…`; with no format, the one the person chose for
+   *  showing dates. The language is the interface's. */
+  format(date: Date, format?: string): string
+  /** The date a text holds under `format`, or null. */
+  parse(text: string, format: string): Date | null
+  /** Whether a date written in `format` can be read back — the test for a format
+   *  used in file names. */
+  isParsableFormat(format: string): boolean
+  /** The format the person chose for showing dates. */
+  appFormat(): string
+  /** Which day a week starts on, numbered as `Date.getDay()` (0 is Sunday). */
+  weekStart(): number
+  /** Weekday names in the interface language, already rotated to start the week
+   *  on `weekStart()`. */
+  weekdayNames(style?: 'short' | 'long'): string[]
+}
+/**
+ * The note open in the active pane, as its editor has it — unsaved typing
+ * included. Positions are offsets into the text, as in {@link PluginLink}.
+ *
+ * Each call looks the note up again, so a handle kept after its tab was closed
+ * answers with an error rather than with text that is no longer on screen.
+ */
+export interface PluginActiveEditor {
+  readonly path: string
+  /** The text in the editor. Needs `vault:read`. */
+  text(): string
+  /** The main selection; `from` = `to` for a bare caret. Needs `vault:read`. */
+  selection(): {
+    from: number
+    to: number
+    text: string
+  }
+  /** Insert at the caret, replacing the selection. Needs `vault:write`. */
+  insert(text: string): void
+  /** Replace `from`–`to`. Needs `vault:write`. */
+  replace(from: number, to: number, text: string): void
+  /** Move the selection (`head` defaults to `anchor`). */
+  select(anchor: number, head?: number): void
+  /** True in reading mode, where edits are refused. */
+  readonly readOnly: boolean
+}
+export interface PluginEditor {
+  /**
+   * Add a CodeMirror extension to every editor, open now or opened later.
+   * Build it from {@link PluginEditor.libs} — the app's own copies — and not from
+   * your own `@codemirror/*` import: two copies of the library in one window do
+   * not recognise each other's objects.
+   */
+  extension(ext: CMState.Extension): Disposer
+  /** The note being edited now, or null when none is open. Every edit goes
+   *  through the editor: it can be undone and is saved like typing. */
+  active(): PluginActiveEditor | null
+  readonly libs: {
+    readonly state: typeof CMState
+    readonly view: typeof CMView
+  }
+}
+export interface PluginResponse {
+  readonly ok: boolean
+  readonly status: number
+  readonly statusText: string
+  readonly headers: Record<string, string>
+  text(): Promise<string>
+  json(): Promise<unknown>
+  /** The body as it came, byte for byte — for pictures and other files. */
+  bytes(): Promise<Uint8Array>
+}
+export interface PluginRequestInit {
+  method?: string
+  headers?: Record<string, string>
+  body?: string
+  /**
+   * Cancels the request. Waiting for the answer, or for its next part, then
+   * fails with an error named `AbortError`, and the connection is closed.
+   */
+  signal?: AbortSignal
+  /**
+   * How long to wait, in milliseconds, without anything arriving — for the
+   * answer to begin, or for its next part — before giving up with an error
+   * named `TimeoutError`. A long answer that keeps arriving is never cut off.
+   * By default 60 s for `fetch` and 120 s for `stream`.
+   */
+  timeoutMs?: number
+}
+/**
+ * An answer that is read as it arrives. The promise that gives it resolves as
+ * soon as the status and headers are in, before any of the body.
+ *
+ * The body is read once, by one of `chunks`, `lines` or `text`; a second read is
+ * an error. Leaving `chunks` or `lines` early (a `break`) closes the connection.
+ */
+export interface PluginStreamResponse {
+  readonly ok: boolean
+  readonly status: number
+  readonly statusText: string
+  readonly headers: Record<string, string>
+  /** The body in the parts it arrives in. */
+  chunks(): AsyncIterable<Uint8Array>
+  /**
+   * The body as UTF-8 lines, without their `\n` or `\r\n` — what server-sent
+   * events and newline-delimited JSON are read with. A character split between
+   * two parts arrives whole.
+   */
+  lines(): AsyncIterable<string>
+  /** The rest of the body as text — for an error's explanation, say. */
+  text(): Promise<string>
+}
+export interface PluginNet {
+  /** Needs `network`. The body is read whole, and an answer over 10 MB fails as
+   *  soon as it passes that size. Only `http:` and `https:`. */
+  fetch(url: string, init?: PluginRequestInit): Promise<PluginResponse>
+  /**
+   * Needs `network`. The same request as {@link fetch}, with the body handed
+   * over as it arrives — for an answer that is written while it is sent, like a
+   * language model's. The 10 MB limit is counted as it goes.
+   *
+   * The request is made outside the window — by the app on a computer, by the
+   * system on a phone — so a server's CORS rules do not apply, and `http:`
+   * reaches machines on the local network on both.
+   */
+  stream(url: string, init?: PluginRequestInit): Promise<PluginStreamResponse>
+}
+/**
+ * Values the plugin must keep apart from its data: access keys, tokens. On a
+ * computer, a file only this user can read (0600, outside the plugin's own
+ * folder, no keychain prompt); on a phone, encrypted by the Android keystore.
+ * The plugin's alone. They survive switching off and updating, and go when the
+ * plugin is removed with its data.
+ *
+ * On a phone without keystore encryption, `set` fails rather than keep the
+ * value in the clear.
+ */
+export interface PluginSecrets {
+  /** The value, or null when none is set. Names: letters, digits, `. _ : -`. */
+  get(name: string): Promise<string | null>
+  set(name: string, value: string): Promise<void>
+  delete(name: string): Promise<void>
+}
+/**
+ * The plugin's own storage, by key — for many records that change one at a
+ * time, where {@link PluginContext.data} would rewrite all of them on every
+ * save. On this device, apart from the notes; kept and removed with the
+ * plugin's data.
+ *
+ * A key is 1–128 letters, digits, `.`, `_` or `-`. A value must survive
+ * `JSON.stringify` and be at most 5 MB written out; a save is whole — after a
+ * crash the key holds the old value or the new one.
+ */
+export interface PluginKeyedStore {
+  get<T = unknown>(key: string): Promise<T | undefined>
+  set(key: string, value: unknown): Promise<void>
+  delete(key: string): Promise<void>
+  /** The keys there are, or only those that start with `prefix`. */
+  keys(prefix?: string): Promise<string[]>
+}
+export interface PluginSearchResult {
+  path: string
+  title: string
+  /** Text around what matched. */
+  snippet: string
+}
+export interface PluginSearch {
+  /**
+   * The notes that match `query`, best first: the app's own search, with its
+   * operators and its order. `limit` defaults to 20 and is at most 200. Needs
+   * `vault:read`.
+   */
+  query(
+    query: string,
+    options?: {
+      limit?: number
+    }
+  ): Promise<PluginSearchResult[]>
+}
+/** Where the app's built-in MCP server is, and the token that opens it. */
+export interface PluginMcpEndpoint {
+  /** The server's address, `http://127.0.0.1:<port>/mcp`. */
+  url: string
+  /** Sent as `Authorization: Bearer <token>`. Treat it as a secret: it reads the person's notes. */
+  token: string
+}
+export interface PluginApp {
+  /**
+   * The address and token of the app's own MCP server, to connect it as one of a
+   * client's servers — or null when the server is off, has no token yet, or this
+   * is a phone. Asked again each time, so it follows the person turning the
+   * server off or making a new token. Needs `network`.
+   */
+  mcp(): Promise<PluginMcpEndpoint | null>
+}
+export interface PluginContext {
+  readonly id: string
+  readonly platform: PluginPlatform
+  readonly apiVersion: typeof PLUGIN_API_VERSION
+  readonly appVersion: string
+  /** The permissions the person agreed to — what the plugin's manifest declared. */
+  readonly permissions: readonly Permission[]
+  /** True when this activation is part of the app starting up, false when the
+   *  person switched the plugin on while the app was running. */
+  readonly startup: boolean
+  readonly commands: {
+    register(command: PluginCommand): Disposer
+  }
+  readonly views: {
+    register(view: PluginView): Disposer
+    /** Show one of this plugin's views: as a panel on a computer (focusing one
+     *  that is already open), and on a phone as its sheet or page. */
+    open(id: string): void
+  }
+  readonly settings: PluginSettings
+  readonly themes: {
+    register(theme: PluginTheme): Disposer
+  }
+  /**
+   * Entries for the app's context menus, after the app's own. `when` decides,
+   * each time a menu opens, whether the entry applies; keep it quick — it runs
+   * while the menu is being drawn.
+   */
+  readonly menus: {
+    /** A note or folder: the file tree and a tab on a computer, the long-press
+     *  actions on a phone. */
+    readonly file: {
+      add(entry: PluginMenuEntry<PluginFileTarget>): Disposer
+    }
+    /** A right click in a note's text, on a computer. */
+    readonly editor: {
+      add(entry: PluginMenuEntry<PluginEditorTarget>): Disposer
+    }
+  }
+  /** Items in the status bar, on a computer. On a phone `add` works and shows
+   *  nothing: there is no status bar. */
+  readonly statusBar: {
+    add(item: { id: string; text: string; title?: string; onClick?: () => void }): {
+      set(patch: { text?: string; title?: string }): void
+      remove(): void
+    }
+  }
+  readonly keys: {
+    /**
+     * Give one of this plugin's commands a shortcut: `Mod+Shift+D` (`Mod` is ⌘
+     * on macOS and Ctrl elsewhere), or several. A combination the app or another
+     * plugin already holds stays theirs; the log says so.
+     */
+    bind(commandId: string, combo: string | string[]): Disposer
+  }
+  readonly events: {
+    on<K extends keyof PluginEvents>(
+      event: K,
+      handler: (payload: PluginEvents[K]) => void
+    ): Disposer
+    on(event: string, handler: (payload: unknown) => void): Disposer
+  }
+  readonly vault: PluginVault
+  readonly metadata: PluginMetadata
+  readonly templates: PluginTemplates
+  readonly dates: PluginDates
+  readonly editor: PluginEditor
+  readonly net: PluginNet
+  readonly secrets: PluginSecrets
+  readonly search: PluginSearch
+  readonly app: PluginApp
+  /** The plugin's own storage, on this device, apart from the notes. Survives
+   *  switching off, updating and — if the person asks — removing. */
+  readonly data: {
+    load<T = unknown>(): Promise<T | undefined>
+    save(value: unknown): Promise<void>
+  }
+  /** Storage by key, beside {@link data}; see {@link PluginKeyedStore}. */
+  readonly store: PluginKeyedStore
+  readonly ui: {
+    notice(message: string, kind?: 'info' | 'error'): void
+    /** The interface language code (`en`, `ru`, …). */
+    language(): string
+    /** Ask the person for a line of text. Resolves with it, or null if they cancel. */
+    prompt(options: {
+      title: string
+      initial?: string
+      placeholder?: string
+      confirmLabel?: string
+      /** Why a value is not acceptable, or null when it is. */
+      validate?: (value: string) => string | null
+    }): Promise<string | null>
+    /**
+     * Offer a list to choose from, narrowed as the person types (by the label,
+     * then the detail). Resolves to the item chosen — the very object passed
+     * in, extra fields and all — or null when the list is closed.
+     */
+    pick<T extends PluginPickItem>(options: { items: T[]; placeholder?: string }): Promise<T | null>
+  }
+  /**
+   * Publish an API for the plugins that depend on this one. `factory` is called
+   * once for each of them, with who is asking; what a dependent registers through
+   * `client.register` is undone when *it* is switched off, so the provider never
+   * has to follow its dependents' lives. Call it once, while activating.
+   */
+  provide(factory: (client: PluginClient) => unknown): void
+  readonly plugins: {
+    /**
+     * The API a plugin this one depends on published. Only for plugins named in
+     * the manifest's `dependencies` — they are guaranteed to be running first;
+     * anything else is undefined. Undefined, too, when the plugin published
+     * nothing. The type is the provider's to document.
+     */
+    get<T = unknown>(id: string): T | undefined
+  }
+  /** Hand over anything of yours that needs undoing; it runs when the plugin is
+   *  switched off, after the registrations above are taken back. */
+  register(disposer: Disposer): void
+  readonly log: {
+    info(...args: unknown[]): void
+    warn(...args: unknown[]): void
+    error(...args: unknown[]): void
+  }
+}
+export interface PluginFileTarget {
+  path: string
+  isFolder: boolean
+}
+export interface PluginEditorTarget {
+  path: string
+  /** The selection, as offsets; `from` = `to` for a bare caret. */
+  from: number
+  to: number
+  text: string
+}
+export interface PluginMenuEntry<T> {
+  /** Short id, unique within the plugin. */
+  id: string
+  title: string
+  when?: (target: T) => boolean
+  run: (target: T) => void | Promise<void>
+}
+/** An entry of {@link PluginContext.ui.pick}'s list. */
+export interface PluginPickItem {
+  label: string
+  /** A second, quieter line. */
+  detail?: string
+}
+/** The plugin asking for a provider's API. */
+export interface PluginClient {
+  readonly id: string
+  /** Undo `disposer` when this client is switched off, updated or removed. */
+  register(disposer: Disposer): void
+  /** Write to the client's own log — for a failure that is the client's doing,
+   *  so its author finds it where they look. */
+  log(level: 'info' | 'warn' | 'error', ...args: unknown[]): void
+}
+/** What a plugin's entry module exports. */
+export interface PluginModule {
+  default?: (ctx: PluginContext) => void | Promise<void>
+  /** Called when the plugin is switched off, before its registrations go. */
+  deactivate?: () => void | Promise<void>
+}
+export {}