Plugin API

Icon Visualizer passes PluginApi and configured options to setup().

type PluginApi = {
  events: {
    on(name, callback): Unsubscribe
    once(name, callback): Unsubscribe
  }
  hooks: {
    filter(name, callback): Unsubscribe
  }
  commands: ConfiguratorCommands
  ui: {
    mount(name, callback): Unsubscribe
    registerLandingSection(section): Unsubscribe
    openModal(options): Unsubscribe
    addStyle(css: string): Unsubscribe
  }
  campaigns: {
    register(campaign): Unsubscribe
  }
  getSnapshot(): Readonly<ConfiguratorSnapshot>
}

Lifecycle

type IconVisualizerPlugin<TOptions extends object> = {
  id: string
  version: string
  apiVersion: '1.0'
  setup(api: PluginApi, options?: TOptions): void | Unsubscribe | Promise<void | Unsubscribe>
  beforeMount?(api: PluginApi, options?: TOptions): void | Promise<void>
  mounted?(api: PluginApi, options?: TOptions): void | Promise<void>
}

setup() registers resources and may return the plugin's top-level cleanup. beforeMount() runs after startup settings are resolved but before the configurator interface mounts. mounted() runs after the interface mounts and before the configurator reports that it is ready.

Late plugins run setup() but do not receive lifecycle callbacks that have already passed.

Plugin definition fields

Field	Required	Contract
id	Yes	Stable ID unique among active plugins.
version	Yes	Plugin-owned release version.
apiVersion	Yes	Supported Plugin API version; currently 1.0.
setup	Yes	Registers capabilities and may return top-level cleanup.
beforeMount	No	Pre-interface lifecycle callback for preboot plugins.
mounted	No	Post-interface lifecycle callback for preboot plugins.

Registration options

type PluginSetupOptions<TOptions extends object> = {
  source?: 'builtin' | 'inline' | 'preboot' | 'late'
  options?: TOptions
  required?: boolean
  order?: number
  capabilities?: PluginCapability[]
}

Plugin authors normally supply options, required, and order. The configurator assigns the registration source. capabilities is advisory metadata and does not create a security boundary.

UI methods

• mount() adds a small contribution to an app-owned outlet.
• registerLandingSection() adds a complete ordered landing section.
• openModal() opens one trusted plugin-rendered modal.
• addStyle() registers CSS for plugin UI inside the configurator.

Campaigns

campaigns.register() adds a structured prompt triggered by supported configurator events. The configurator owns presentation behavior, action execution, frequency, and cleanup.

Snapshot

getSnapshot() returns the same read-only public status shape described in Registration and diagnostics types.