Jitzy

Jitzy is a high-performance WebGL runtime that brings your DOM to life. Attach markers to any element on the page, draw animated connectors between them, and let a smart topology engine decide what should connect — all on a single GPU-accelerated canvas layered over your layout.

Built by Fiddle.Digital.

npm install @fiddle-digital/jitzy

Overview

What is Jitzy?

Jitzy turns ordinary HTML elements into nodes of a living, interactive network. Whether you're building a product map, a node-based editor, an architecture diagram, a hero section with reactive lines, or a data-driven landing page, Jitzy handles the hard parts — element tracking, scroll sync, pointer interaction, hit testing, and rendering — so you can focus on the idea.

Key Features

• WebGL Rendering: Markers, labels, and connectors are drawn on one hardware-accelerated canvas, with an automatic safe fallback.
• DOM-Attached: Markers follow your real elements through scrolling, resizing, and layout changes.
• Smart Topology: Five connection modes decide what connects — from cursor-reactive networks to a fully manual graph.
  • Field-weighted nearest
  • Magnetic flux
  • Neural activation
  • All-pairs mesh
  • Explicit connections
• Flexible Routing: Straight, arc, and card-avoiding smart connectors.
• Pointer Interaction: Cursor proximity shapes the network, and clicks on markers, labels, and connectors are one event away.
• Fluent API: jitzy.element(a).connect(b) — connections read like a sentence.
• Extensible: Plugins, custom animation strategies, topology strategies, and render backends.
• Effortless Initialization: One Jitzy.mount() call owns the whole lifecycle.

Who is Jitzy for?

Jitzy is perfect for:

• Beginner Developers: Create a connected, animated overlay with a handful of lines and no graphics knowledge.
• Experienced Developers: Reach for topology strategies, custom renderers, and the plugin SDK when you need full control.
• Designers: Bring network-style visuals to a layout without leaving the HTML you already have.

Introduction

Why Jitzy?

Connecting elements on a web page sounds simple until it isn't: positions shift on scroll, layouts reflow on resize, hundreds of lines fight for the main thread, and every click needs hit testing. Jitzy takes all of that off your plate. It focuses on simplicity, performance, and extensibility, so the distance between "I have an idea" and "it's on screen" stays short.

Benefits of Using Jitzy

1. Simplicity: Mount once, register your elements, connect them. No manual measuring, no render loop to write.
2. Performance: Everything is drawn in WebGL on a single canvas, built to stay smooth on busy pages.
3. Flexibility: Let the topology engine choose connections for you, or declare each one yourself.
4. Extensibility: Start with the built-in baseline look and grow with plugins, themes, and custom renderers.
5. Type Safety: Written in TypeScript, with a fully typed public API.

Core Principles

• Your DOM is the source of truth: Markers attach to real elements and follow them automatically.
• Declarative first, programmable always: Describe markers in config, and reach for the fluent API when you need control.
• One lifecycle, one owner: Jitzy.mount() bootstraps the renderer, observers, interaction tracking, and render loop, and dispose() cleans all of it up.
• Extensible by design: Everything beyond the baseline plugs in through the plugin SDK.

Getting Started

Installation

npm install @fiddle-digital/jitzy

Quick Start

import { Jitzy } from "@fiddle-digital/jitzy";

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

const jitzy = 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",
});

That's it. Two cards, two markers, one living connector.

What Jitzy.mount() does for you

• Bootstraps the renderer (WebGL, with an automatic no-op fallback)
• Wires up the target observer
• Syncs surface metrics on resize
• Tracks pointer movement and scrolling
• Runs the internal render loop
• Cleans everything up on jitzy.dispose()

⚠ Note: mount() is synchronous and returns a ready-to-use instance. Pass a container element that already exists in the DOM.

Core API

Lifecycle

| Method | Description | | ---------------------------------- | -------------------------------------------------------- | | Jitzy.mount(container, options?) | Bootstrap factory — returns a ready Jitzy instance | | jitzy.refresh(forceMeasure?) | Force a fresh measurement and render | | jitzy.dispose() | Tear down the engine, observers, listeners, and renderer |

Targets

A target is a DOM element that carries one or more markers.

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

| Method | Description | | ------------------------------------ | -------------------------------------------- | | jitzy.addTarget(element, config) | Register an element with markers | | jitzy.registerTarget(registration) | Register with a full registration object | | jitzy.updateTarget(registration) | Update an existing registration | | jitzy.removeTarget(id) | Unregister a target | | jitzy.hasTarget(id) | Check whether a target is registered |

Connections

Fluent:

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

Explicit:

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

| Method | Description | | ---------------------------------------- | ------------------------------------ | | jitzy.element(ref).connect(target) | Create a connection (fluent) | | jitzy.element(ref).disconnect(target) | Remove a connection (fluent) | | jitzy.addConnection(from, to, options) | Create a connection (explicit) | | jitzy.removeConnection(from, to) | Remove a connection (explicit) | | jitzy.clearConnections() | Remove all programmatic connections | | jitzy.getConnections() | List active connections | | jitzy.isConnected(from, to) | Check whether two elements connect |

Events

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

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

Jitzy also emits label:click, connect, and disconnect.

Hit Testing

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

Topology Modes

Topology decides which markers get connected. Pick the behavior that fits your story:

| Mode | What it does | | ------------------------ | ---------------------------------------------------------------------- | | field-weighted-nearest | Scores pairs by distance, cursor proximity, and scroll phase | | magnetic-flux | Favors connectors whose endpoint is close to the cursor | | neural-activation | Both endpoints must be near the cursor — the network "fires" locally | | all-pairs | A full mesh — every marker connects to every other marker | | explicit | Only the connections you declare |

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

Extending Jitzy

Jitzy ships with a neutral baseline look that is registered automatically — no setup needed. When you want more, the engine opens up:

• Plugins — register marker styles, connector styles, animations, and themes with jitzy.use(plugin), and switch looks with jitzy.applyTheme(themeId).
• Topology strategies — add your own connection logic with registerTopologyStrategy(mode, factory).
• Render backends — registerRenderer(backend, factory) exposes the renderer registry for advanced integrations.

The Jitzy Ecosystem

| Package | Purpose | | ---------------------------------------------------------------- | -------------------------------------------------------------------- | | @fiddle-digital/jitzy | The runtime engine and public integration surface (this package) | | @fiddle-digital/jitzy-plugin-sdk | Build your own plugins, themes, animations, and connector styles | | @fiddle-digital/jitzy-three | Project Three.js world-space anchors into Jitzy targets |

When to Use Jitzy

• To visualize relationships between elements — cards, nodes, sections, products.
• To add a reactive, cursor-aware network to a landing page or hero.
• To build node-based interfaces with drag-to-connect interactions.
• To enhance engagement with a layer that feels alive but stays out of your layout.

License

© Fiddle.Digital. All rights reserved. This package is proprietary software.

Get started with Jitzy today and give your interfaces a pulse.