@jitzy/core

High-performance WebGL runtime for DOM-attached markers, connectors, and interactive topology overlays.

@jitzy/core renders animated markers and connector lines on a GPU-accelerated canvas layered over your page. It handles element tracking, topology selection, pointer interaction, scroll sync, hit testing, and rendering lifecycle out of the box.

Install

npm install @jitzy/core

What It Does

• Renders markers, labels, and connectors in WebGL
• Attaches visual state to existing DOM elements
• Supports dynamic and explicit connection topologies
• Tracks pointer movement, scrolling, and layout changes
• Exposes fluent and explicit APIs for connections
• Supports plugins, custom animation strategies, and custom renderers

Quick Start

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

const surface = document.getElementById("canvas-container")!;

const jitzy = await Jitzy.mount(surface, {
  topology: { mode: "field-weighted-nearest" },
  connector: {
    color: "rgba(255, 51, 68, 0.85)",
    width: 2,
    curvature: 0.35,
    curvatureMode: "outward",
  },
});

jitzy.addTarget(document.getElementById("card-a")!, {
  id: "card-a",
  markers: [{ id: "out", xPercent: 100, yPercent: 50, label: "OUT" }],
});

jitzy.addTarget(document.getElementById("card-b")!, {
  id: "card-b",
  markers: [{ id: "in", xPercent: 0, yPercent: 50, label: "IN" }],
});

jitzy.element({ target: "card-a", marker: "out" }).connect({
  target: "card-b",
  marker: "in",
});

Lifecycle

Jitzy.mount() bootstraps the runtime and owns:

• renderer initialization
• resize and surface metrics sync
• target observation
• pointer and scroll tracking
• the internal render loop

Dispose with:

jitzy.dispose();

Force a fresh measurement and render with:

jitzy.refresh();

Core API

Register targets

jitzy.addTarget(element, {
  id: "node-a",
  markers: [{ id: "out", xPercent: 100, yPercent: 50 }],
});

Create connections

Fluent API:

jitzy.element({ target: "node-a", marker: "out" }).connect({
  target: "node-b",
  marker: "in",
});

Explicit API:

jitzy.addConnection(
  { target: "node-a", marker: "out" },
  { target: "node-b", marker: "in" },
);

Listen to events

jitzy.on("marker:click", ({ targetId, markerId }) => {
  console.log(targetId, markerId);
});

jitzy.on("connector:click", ({ from, to }) => {
  console.log(from, to);
});

Hit testing

const hit = jitzy.hitTest(clientX, clientY);

Topology Modes

• field-weighted-nearest
• magnetic-flux
• neural-activation
• all-pairs
• explicit

Example:

jitzy.setTopologyConfig({
  mode: "field-weighted-nearest",
  maxConnectors: 20,
  maxPerMarker: 2,
  distanceSigmaPx: 220,
  cursorRadiusPx: 260,
  distanceWeight: 0.55,
  cursorWeight: 0.3,
  scrollWeight: 0.15,
});

Extensibility

Register a custom renderer:

import { registerRenderer } from "@jitzy/core";
import type { IRenderer } from "@jitzy/core";

class MyCanvasRenderer implements IRenderer {
  // implement renderer contract
}

registerRenderer("canvas2d", () => new MyCanvasRenderer());

Register custom animation or theme packs through the public plugin contract exposed by @jitzy/plugin-sdk.

Package Scope

@jitzy/core contains the runtime engine and public integration surface.

If you want to build custom plugins, themes, animation packs, or renderer extensions, use @jitzy/plugin-sdk alongside this package.

License

MIT