← All work
Creative tech · WebGL

chroma-gem

Deterministic, WebGL-accelerated procedural crystal generation. Brand-grade generative geometry rendered in real time.

TypeScript Private repo
View example ↗

chroma-gem is a deterministic, webgl-accelerated React package for generating and rendering brand-grade procedural crystalline structures across web properties.

Build Targets

  • npm run dev: spin up the local live-tuning studio app.
  • npm run build:app: compile the studio UI bundle for production deployment to /dist/demo.
  • npm run package / npm run build:package: pack the raw, tree-shakable engine export to /dist.

Engine Features

  • Geometry Arrays: Six core architectural plotting algorithms mapping space via hex matrices, radial rings, and cartesian triangles.
  • Cinematic Processing: Realtime integrated shader passes out-of-the-box (Vignette, Film Grain, Component Chromatic Aberration).
  • Thematic Bleeds: Deterministic geometry overfill allowing physical geometry to expand bounded frames through custom grayscale / darken composition filters.
  • Fluid Topology: Mathematical temporal mechanics driving interactions to blur, decay, and carry momentum across facet networks like liquid paint.
  • Reactive Flow: Zero-click wave generators reading cursor velocity paths dynamically.
  • Strict Determinism: Zero reliance on runtime PRNG (Math.random(), Date.now()). All topological variations generate strictly through deterministic id hashing to guarantee identical states across identical props. Even user-saved custom profiles and UI themes compute their id keys derived directly from the exact content of their serializable payloads via hashing algorithms.

Package Integration

  1. Add the package to a consuming project.
  2. Render instances leveraging independent configurations:
import { BrandGem } from "chroma-gem";

export function HeroBlock() {
  return (
    <header className="relative w-full h-96 overflow-hidden">
        {/* Render a full-width Dense Matrix layout acting as a canvas */}
      <BrandGem
        variant="gem24"
        scenario="scroll-reactive"
        seed="company-hero-2026"
        className="w-full h-full"
        config={{
            geometry: { mode: "dense-matrix" },
            bleed: { margin: 200, hardCrop: true, theme: "grayscale", facets: true },
            theme: { postConfig: { filmGrainAmount: 0.15, vignetteStrength: 0.8 } }
        }}
       />
    </header>
  );
}

When config is omitted, the instance leverages DEFAULT_APP_CONFIG. Any partial object provided to config will strictly override base presets.

Configuration API (AppConfig)

The engine behavior is governed by a deeply nested AppConfig interface exposing five core modules:

export interface AppConfig {
  geometry: {
    mode: "locked24" | "overlap7" | "ring12" | "triforce" | "diamond" | "dense-matrix";
    revealMode: "center-out" | "top-down" | ... | "random";
    revealStyle: "fade" | "scale" | "wire-to-fill" | "shimmer-flow";
    revealDurationMs: number;
    overlapInnerRadius: number; // Structure base density
    jitterStrength: number;     // Positional chaos modifier
  };

  bleed: {
    margin: number;     // Absolute px outer-bound expansion limit for geometry
    facets: boolean;    // Allow polygons to break visual bounding box
    wireframes: boolean;// Allow skeletal linework to break bounds
    hardCrop: boolean;  // Enforce a strict absolute square-crop mask
    theme: "same" | "grayscale" | "ghost" | "darken"; // Visual filter for over-bleed artifacts
  };

  rendering: {
    facetStrokeOpacity: number;
    facetStrokeWidth: number;
    facetFillOpacity: number;
  };

  wireframes: {
    triMesh: WireframeStyle;
    hexSkel: WireframeStyle;
    connects: WireframeStyle;
    hexNodes: WireframeStyle;
    nodeLinks: WireframeStyle;
  };

  diffusion: {
    enabled: boolean;
    diffSteps: number;          // Blur resolution iterations
    diffMix: number;            // Mixing strength
    viscosity: number;          // Fluid resistance mapping (0.01 - 1.0)
    thermalDecay: number;       // Rate introduced colors normalize back to base theme
    neighborDiffStrength: number;
    hueShift: number;           // Absolute hue rotation on injected events
    saturationDecay: number;    // Absolute saturation dropoff per interval
  };

  wave: {
    stepDelayMs: number;
    activeMs: number;
    sustainMs: number;
    falloffMs: number;
    autoPulse: boolean;
    autoPulseInterval: number;
    trailDecayEnabled: boolean;
    trailDecayRate: number;
    hoverFlowEnabled: boolean;   // Activate cursor-move liquid physics
    hoverFlowIntensity: number;  // Magnitude of the wake
  };

  theme: {
    brushColor: RGB;
    postConfig: {
      contrast: number;
      brightness: number;
      saturation: number;
      filmGrainAmount: number;   // Analog SVG noise factor (0 - 1.0)
      vignetteStrength: number;  // Radial overlay black-point (0 - 1.0)
      chromaAberration: number;  // Glitch-tier RGB channel splitting
    };
    stops: GradientStop[];       // Core canvas global gradient map
  };
}

Note: The WireframeStyle exposes deep independent layered logic for each slice: { enabled, opacity, thickness, layer: 'top'|'bottom', pathType: 'solid'|'dashed'|'dotted', placement: 'inside'|'center'|'outside', fillMode: 'none'|'hash'|'band'|'radius'|'angle' }

Headless & Realtime Overrides

If you require dynamic input sliders bound securely to engine state (without importing the studio sidebars), wrap arbitrary React trees inside RealtimeGemProvider and invoke the useRealtimeGem() hook.

import { RealtimeGemProvider, RealtimeGemCanvas, useRealtimeGem } from "chroma-gem";

function HeadlessControls() {
  const { checkpoint, geometryMode, setGeometryMode, setHoverFlowEnabled } = useRealtimeGem();
  return (
    <div className="flex gap-4 p-4 absolute z-10 bottom-0">
        <button onClick={() => { checkpoint(); setGeometryMode("diamond"); }}>
            Engage Diamond Lattice
        </button>
        <button onClick={() => { setHoverFlowEnabled(true); }}>
            Engage Fluid Topology
        </button>
    </div>
  );
}

export function InteractiveAppView() {
  return (
    <RealtimeGemProvider>
      <div className="relative h-screen w-full bg-black">
        <RealtimeGemCanvas />
        <HeadlessControls />
      </div>
    </RealtimeGemProvider>
  );
}

Exported Sub-Modules

  • Core UI: BrandGem, RealtimeGemCanvas, GemStaticPreview
  • Context API: RealtimeGemProvider, useRealtimeGem
  • Default Presets: DEFAULT_APP_CONFIG, DEFAULT_GEM_24_CONFIG
  • Runtime Safeties: normalizeBrandConfig, applySeedToConfig
  • Type Definitions: AppConfig, GeometryMode, WireframeStyle, Theme, RGB

Style Inclusion

The package requires base canvas layout classes compiled locally. If your bundler ignores automatic CSS injection, manually import the global styles: import "chroma-gem/style.css". The exported package does not include the internal studio styling dependencies (Tailwind arbitrary variants or Radix un-styled primitives).

Architecture & Philosophy

While elements of chroma-gem use standard web technologies (React, SVG, Float32Arrays), the way they are combined is highly unconventional for a frontend web application. It is operating essentially as a headless physics engine puppeteering standard DOM elements.

1. Bypassing the React VDOM for Physics

In a standard React application, heavily animating 500+ SVG nodes at 60fps would crush the browser's main thread during reconciliation. Instead, chroma-gem acts as an Imperative DOM Synchronizer. React's only job is to render the SVG skeleton once. Every <FacetItem> passes its raw <polygon> DOM reference back up to a central Map. A compositor then runs a raw requestAnimationFrame loop using fast 1D Float32Arrays to calculate physics, and imperatively mutates the DOM (node.style.opacity = result), completely ignoring React's Virtual DOM.

2. Topological BFS instead of Euclidean Math

In common web visualizers, ripple effects use Euclidean math (Math.hypot), calculating a circle against the center of every element. Because chroma-gem uses irregular geometries (hexagons overlapping with triangles), Euclidean math looks bad and crosses boundaries it shouldn't. Instead, the engine pre-computes a strict Mathematical Graph (TopoMesh.facetNeighbors). When a user clicks, the engine runs an integer-based Breadth-First-Search (BFS) over the neighbor array. The wave propagates topologically from neighbor to neighbor organically, like real liquid constraints.

3. Strict "No-PRNG" Determinism Contract

Most frontend apps freely use Math.random() for visual jitter and uuidv4() or Date.now() for generating component keys and saved profiles. By strictly adhering to a No-PRNG determinism contract, chroma-gem ensures that the identical AppConfig payload will render the exact same frame, byte-for-byte on any machine, at any time.

4. Fragment-Shader Logic in JavaScript

The color pipeline mixes overlaps essentially bringing GLSL shader math into plain React JavaScript. Using Continuous-Time equations (exp(-lambda * dt)), Bounded Unions, and Smoothstep Transfer Curves to safely clamp overlapping colors prevents the screen from blowing out into pure #FFFFFF white when multiple waves hit the same polygon.