Plugins (painter.plugins, painter.use)

Apexify.js exposes two related extension mechanisms:

1. painter.plugins (PluginHost) — a name → API-object registry.
2. await painter.use(plugin) — transactional plugin installation with one installation per plugin name.

ApexPainter.use is asynchronous. Always await it. The method resolves to the painter instance only after plugin.install(host) has completed.

#painter.plugins registry

1import { ApexPainter } from "apexify.js";2 3const painter = new ApexPainter({ type: "buffer" });4 5const myToolkit = painter.plugins.use("analytics", {6  track(_event: string, _payload?: Record<string, unknown>) {7    /* ... */8  },9});10 11const tk = painter.plugins.get<typeof myToolkit>("analytics");12tk?.track("render_ok");

Registry contract:

• use(name, api) validates the name and rejects duplicate API names with ApexifyPluginError.
• get<T>(name), has(name), list() inspect registered APIs.
• remove(name) deletes an API entry.
• isInstalled(name), listInstalled() inspect completed ApexifyPlugin installations.

API names and plugin names must be non-empty identifier-like strings.

#await painter.use(plugin)

1import { ApexPainter, type ApexifyPlugin, type SceneLayer } from "apexify.js";2 3const watermarkHelper: ApexifyPlugin<ApexPainter> = {4  name: "watermark-kit",5  async install(p) {6    // Async setup is supported and awaited.7    await Promise.resolve();8 9    p.plugins.use("watermark-kit", {10      cornerLabel(text: string): SceneLayer[] {11        return p.components.watermark.toLayers({12          text,13          canvasWidth: 640,14          canvasHeight: 360,15          position: "bottom-right",16          margin: 16,17          fontSize: 12,18          color: "#94a3b81a",19        });20      },21    });22  },23};24 25const painter = new ApexPainter({ type: "buffer" });26await painter.use(watermarkHelper);27 28const kit = painter.plugins.get<{ cornerLabel: (text: string) => SceneLayer[] }>("watermark-kit");29const layers = kit?.cornerLabel("staging") ?? [];30 31await painter.renderScene({32  width: 640,33  height: 360,34  background: { colorBg: "#020617" },35  layers,36});

#Lifecycle and duplicate semantics

• Calling painter.use() twice with the same plugin.name is rejected.
• A second same-name call is also rejected while the first installation is still pending.
• Different plugin installations are serialized so plugin transactions do not overlap.
• A failed plugin name is released after cleanup, so the application may retry that plugin later.
• The current lifecycle is install-only. Apexify.js does not provide plugin uninstall/teardown hooks.

#Failure rollback

PluginHost uses an async-context transaction around plugin.install(host). If install() throws or rejects:

• API registrations made through host.plugins.use(...) inside that plugin installation are removed.
• Pre-existing PluginHost APIs removed by the failing plugin are restored.
• Unrelated application registry writes that happen concurrently while the plugin is awaiting are preserved.
• The plugin is not marked installed.
• The caller receives ApexifyPluginError with the original error as its cause.

Rollback is intentionally limited to PluginHost registry mutations performed in the plugin installation context. Apexify.js cannot automatically undo arbitrary external side effects performed by plugin code (files, network calls, timers, mutations to unrelated application state). Plugins should perform irreversible side effects only after their own prerequisites are known to have succeeded, or provide their own compensation logic.

#Type safety

1import type { ApexifyPlugin, ApexPainter } from "apexify.js";2 3const plugin: ApexifyPlugin<ApexPainter> = {4  name: "typed-plugin",5  async install(host) {6    host.plugins.use("typed-api", {7      renderCount: 0,8    });9  },10};

ApexifyPlugin<T> types the installation host. PluginHost.get<T>() lets consumers recover the registered API type at the lookup site.

#When to use which