plugin-api.md

Lattice Plugin API

The plugin API is the WIT package lattice:plugin-host@0.1.0 — 31 interfaces ("seams") and 25 worlds. It is the whole contract: a plugin written in any language with Component-Model tooling (Rust, Go, Zig, JavaScript, …) sees exactly what is on these pages and nothing else. This reference is generated from the .wit files in crates/lattice-wit/wit/, so it cannot disagree with them.

New to writing plugins? Start with the plugin authoring guide, then come back here for the detail. The same reference in machine-readable form — every seam, signature, type and member — is docs/dev/reference/plugin-api.json in the repository and /plugin-api.json on the documentation site.

How to read this reference

• A plugin targets one world. The world decides which seams the plugin exports (implements — the host calls it) and which it imports (calls into the host). In Rust: wit_bindgen::generate!({ world: "comment-plugin", path: "…/wit" }).
• Direction on each seam says which of those it is. A seam marked shared types only is never called; other seams use its types.
• Capability is what the seam requires of a plugin's grant. Most are none: the host does the I/O and hands the guest data.
• Resources (resource document) are handles to host-owned state. A borrow<document> parameter is valid for that call only.
• Errors are result<T, string>: an err carries a message the host surfaces to the user, so it should say what went wrong.
• WIT to Rust (wit-bindgen): kebab-case becomes snake_case for functions and fields and UpperCamelCase for types; list<T> is Vec<T>, option<T> is Option<T>, result<T, E> is Result<T, E>, borrow<r> is &R.

Worlds (25)

Each world's entry points — the register-* functions the host calls on load — are on the worlds page.

World	Exports (you implement)	Imports (you may call)
auto-pair-plugin	grammar-callbacks; register-grammar, register-modes, register-options, register-help-topics	buffer, config, grammar, help, modes, tree-sitter, types
comment-plugin	grammar-callbacks; register-grammar, register-modes, register-options, register-help-topics	buffer, config, grammar, help, modes, tree-sitter, types
completion-source-plugin	completion-source	host-services, logging, project, types
config-plugin	register-options	config, logging, project
context-plugin	context	host-services, logging, project, tree-sitter, types
dashboard-plugin	register-dashboard-sections, render-section	dashboard, logging, project
decorations-plugin	decorations	host-services, logging, project, types
error-parser-plugin	reset, feed	error-parser, logging
events-plugin	register-events, on-event, on-wake	events, host-services, logging, multibuffer-view-registry, project, types
grammar-plugin	grammar-callbacks; register-grammar	buffer, grammar, tree-sitter, types
help-plugin	register-help-topics	help, logging, project
keymap-plugin	register-keymap	keymap, logging, project
language-plugin	register-languages	language, logging, project
media-plugin	media	host-services, logging, project, types
modes-plugin	register-modes	logging, modes, project
multibuffer-view-plugin	multibuffer-view-source; register-multibuffer-views	host-services, logging, multibuffer-view-registry, project, types
picker-source-plugin	picker-source; register-picker-sources	host-services, logging, picker-registry, project, types
plugin	activate, deactivate	buffer, host-services, logging, project, types, ui
plugin-manager-plugin	register-plugins	logging, plugin-manager, project
project-plugin	grammar-callbacks, picker-source, transient-source; register-grammar, register-picker-sources, register-modes, register-options, register-help-topics, register-events, on-event, on-wake	buffer, config, events, grammar, help, host-services, modes, picker-registry, project, tree-sitter, types
scanned-excerpt-source-plugin	extensions, view-mode, roots, begin, describe, scan	config, logging, project, scanned-excerpt-source, tree-sitter, types
sign-plugin	register-signs	logging, project, signs
theme-plugin	register-theme-elements	logging, project, theme
transient-source-plugin	transient-source	logging, project, types
treesitter-context-plugin	context, grammar-callbacks; register-options, register-grammar, register-modes, register-help-topics	buffer, config, grammar, help, modes, tree-sitter, types

Seams (31)

Seam	Direction	Capability	Functions	Types	Summary
buffer	imports	-	5	2	Mirrors the native Document / Buffer read seam (plugin-host.md §4.2, §9.6).
command	types	-	0	0	Mirrors CommandRegistry + CommandInvocation + the closed Effect enum (lattice-grammar).
completion-source	exports	-	2	0	Mirrors lattice_completion completion sources (PH7.6).
config	imports	-	8	7	Mirrors ConfigRegistry (lattice-config).
context	exports	-	1	0	The structural-context producer API (treesitter-context.md, TC.2): the scopes a pane pins above its text once their own header lines have scrolled away — the nvim-treesitter-context / sticky-scroll idea.
dashboard	imports	-	1	7	CR.4: plugin-contributed dashboard sections.
decorations	exports	-	1	0	The decoration producer API (plugin-host.md §5 decorations, PH7.9), mirroring Mode::gutter_decorations + GutterDecoration (lattice-mode).
error-parser	types	-	0	2	CM.6: plugin-contributed compilation-output parsers.
events	imports	-	3	1	The event/hook subscription API (plugin-host.md §5 events, PH7.8).
grammar	imports	-	5	0	The grammar-extension API (plugin-host.md §4.1, PH7.7).
grammar-callbacks	exports	-	6	0	The behavior callbacks a grammar plugin exports; the host calls one by callback id on dispatch (the PH7.3d callback-id trampoline).
help	imports	-	1	0	CR.3: plugin-contributed :help pages.
host-services	imports	fs	20	1	Guest→host services (plugin-host.md §5).
keymap	imports	-	1	1	The keymap guest→host binding-registration seam (PL8.D.1).
language	imports	-	1	2	LG.3c: plugin-contributed languages.
logging	imports	-	1	1	Guest→host structured logging (plugin observability Layer 2, design docs/dev/architecture/plugin-observability.md §8).
media	exports	-	1	0	The inline-media producer API (IM.6, inline-media.md §7).
modes	imports	-	3	8	Mirrors the Mode trait declaration surface + ModeRegistry (lattice-mode).
multibuffer-view-registry	imports	-	2	0	MV.1 — the seam by which a plugin owns a multibuffer view.
multibuffer-view-source	exports	-	1	0
picker-registry	imports	-	1	0	OR.5b — the host import a picker plugin registers its sources through.
picker-source	exports	-	2	1	Mirrors PickerSourceGenerator (lattice_picker::source).
plugin-manager	imports	proc	1	3	PM.7: the require seam — how a user's init.rs declares the plugins it wants (plugin-manager.md §3).
project	imports	fs	2	2	Guest→host project resolution (PR.6, design docs/dev/architecture/project-resolution.md §6).
scanned-excerpt-source	types	-	0	4	OM.A1: plugin-contributed agenda rows.
signs	imports	-	1	1	Mirrors the sign registry (lattice_mode::SignRegistry).
theme	imports	-	2	3	Mirrors the theme-element registry (lattice-theme).
transient-source	exports	-	2	0	TR.2b: plugin-contributed transient menus.
tree-sitter	imports	-	25	6	Structural queries for plugins (plugin-treesitter-seam.md).
types	types	-	0	147	Shared boundary records/variants — the owned, WIT-serializable mirrors of the native grammar + picker/completion types (plugin-host.md §4).
ui	imports	-	3	0	The UI-contribution surface (design.md §9.4 ui): guest→host emits data only, never draw calls (§7, paramount #1).