@jitzy/plugin-sdk

Plugin SDK for building custom Jitzy animations, themes, connector styles, and renderer extensions.

@jitzy/plugin-sdk is the authoring surface behind Jitzy plugin packs. Use it to define reusable animation packs, style packs, and themes that plug into @jitzy/core.

Install

npm install @jitzy/plugin-sdk

Most plugin authors will also use:

npm install @jitzy/core

What It Is For

• custom marker animation strategies
• custom marker, label, and connector styles
• reusable theme packs
• low-level WebGL helper utilities
• type-safe plugin contracts shared with @jitzy/core

Define a Plugin

Use definePlugin(...) to package assets into a plugin object consumable by jitzy.use(...).

import { definePlugin } from "@jitzy/plugin-sdk";

export const myPlugin = definePlugin({
  name: "my-plugin",
  version: "0.0.2",
  markerStyles: [
    {
      id: "soft-pin",
      config: {
        shape: "circle",
        radius: 8,
        color: "#ff3344",
      },
    },
  ],
  connectorStyles: [
    {
      id: "signal-line",
      config: {
        color: "rgba(255, 51, 68, 0.8)",
        width: 2,
        curvature: 0.35,
        curvatureMode: "outward",
      },
    },
  ],
  themes: [
    {
      id: "signal",
      markerStyle: "soft-pin",
      connectorStyle: "signal-line",
    },
  ],
});

Then register it in @jitzy/core:

import { Jitzy } from "@jitzy/core";
import { myPlugin } from "./myPlugin";

const jitzy = await Jitzy.mount(surface);
jitzy.use(myPlugin);
jitzy.applyTheme("signal");

Plugin Shape

A plugin can contain:

• animations
• carrierStyles
• connectorStyles
• markerStyles
• labelStyles
• themes

Minimal shape:

import { definePlugin } from "@jitzy/plugin-sdk";

export const plugin = definePlugin({
  name: "example-pack",
  version: "0.0.2",
});

definePlugin(...) also fills sdkVersion automatically when omitted.

Themes and Style Assets

Themes are references to previously declared assets.

import { definePlugin } from "@jitzy/plugin-sdk";

export const themePack = definePlugin({
  name: "theme-pack",
  version: "0.0.2",
  markerStyles: [
    {
      id: "node",
      config: {
        shape: "circle",
        radius: 7,
        color: "#111111",
      },
    },
  ],
  connectorStyles: [
    {
      id: "wire",
      config: {
        color: "rgba(17, 17, 17, 0.75)",
        width: 2,
      },
    },
  ],
  themes: [
    {
      id: "mono",
      markerStyle: "node",
      connectorStyle: "wire",
    },
  ],
});

Custom Marker Animations

The SDK exports the animation strategy contract and helper utilities for time-based effects.

import {
  definePlugin,
  loop,
  type WebGLMarkerAnimationStrategy,
} from "@jitzy/plugin-sdk";

class PulseAnimation implements WebGLMarkerAnimationStrategy {
  // implement the strategy contract
}

export const animationPack = definePlugin({
  name: "pulse-pack",
  version: "0.0.2",
  animations: [
    {
      mode: "pulse",
      factory: PulseAnimation,
    },
  ],
});

const t = loop(1250, performance.now());

Low-Level Utilities

The SDK also exports lower-level helpers for plugin authors working directly with WebGL:

• compileShader
• compileProgram
• parseColor
• WebGLSpriteBatch
• animation timing helpers like loop and pingPong

Use these only if you are building custom rendering or animation strategies. Most theme/style packs do not need them.

Compatibility

Plugins are versioned against the SDK contract. definePlugin(...) sets sdkVersion automatically, and @jitzy/core can reject incompatible packs at runtime.

Keep @jitzy/core and @jitzy/plugin-sdk on compatible versions when publishing third-party packs.

Package Scope

@jitzy/plugin-sdk is not the runtime engine. It is the extension contract for authors building on top of Jitzy.

If you want to mount overlays and connect DOM targets, use @jitzy/core.

License

MIT