Core Concepts

The Concepts section is the mental-model side of Plugin Kit. Each page covers one piece of the runtime’s vocabulary: what it is, how it fits with the others, and the design choices behind it. The reference is for looking up signatures; guides are for action-oriented walkthroughs; the pages here are for understanding the model that makes the rest cohere.

How the pieces fit

A plugin has an identity and a lifecycle. The runtime decides which plugins are enabled, calls their register hook to collect services into the registry, then calls attach to start them. Plugin services are the classes a plugin owns; the registry stamps identity onto them and injects settings when they resolve.

The service registry is where competition happens. Two plugins can register for the same slot; the higher priority wins, and the loser stays reachable as a fallback. Capabilities are metadata that travel with each registration so host code can inspect what a slot supports without building anything.

The event bus is how plugins coordinate without holding references to each other. Typed events flow in priority order; typed requests fall through handlers until one returns a non-null response. Event Patterns, the page next to event bus, covers the patterns for using all of this from inside plugin code rather than the model itself.

The runtime owns the global scope and spawns sessions. A session is an isolated execution scope with its own registry and bus; opening a second session never disturbs the first. The runtime holds a settings snapshot and exposes a change stream so the host can hand it new RuntimeSettings and have it converge.

Custom contexts are the optional extension point: when your domain has fields that every plugin in a session should see (the current document, the active user, a tool registry), you subclass SessionPluginContext and supply a factory.

The pages

Plugins The unit the runtime cares about. Identity, lifecycle, scope (Global vs Session), feature flags, and the four hooks every plugin can override.

Plugin Services Where stateful behavior lives. `PluginService` for typed config, `StatefulPluginService` for session-bound subscriptions and tracked cleanup.

Service Registry Priority-based DI where multiple plugins can claim the same slot. `resolveAfter` for fallback layering. Wildcard overrides and namespaces.

Capabilities Metadata tags attached to registrations so host code can discover what a service supports without instantiating it.

Configuration `ConfigNode`, the typed read-only view a service uses to consume injected settings. Coercion rules and what the registry guarantees.

Event Bus The model. Typed handlers, priority order, the envelope, request/response, identifier scoping, cross-scope routing.

Event Patterns Patterns for using the bus from inside plugin code. Designing event types, the pre-commit interception pattern, common pitfalls.

Runtime The lifecycle engine. `PluginRuntime`, `PluginRuntime`, settings reconciliation, enablement precedence.

Sessions Per-session isolation, the global vs session bus split, and explicit cross-scope routing.

Custom Contexts Extending `PluginContext` with domain-specific fields like the current document, user, or tool registry. When to do it and when not to.

The sidebar order is the order most readers find useful (smallest unit outward to the things that move plugins around), but every page links to the others it depends on.

Where to next

API reference Curated reference for the public types, organized by intent: plugins, registry, bus, settings, dialog.

Guides Action-oriented walkthroughs. Add a plugin, wire it into Flutter, configure it, log it, test it.

Architecture The internal type hierarchy, dispatch model, and design rationale, for contributors and curious readers.