Meridian Halo

A polished, animated particle halo built with Three.js. Drop it into a web page via a script tag, or import it in modern apps as ESM/CJS. Includes external and standalone browser bundles and a minimal, documented API.

Demo

Run the local demos:

npm run demo:serve

Open:

• External Three (script tag): http://localhost:8080/demo/
• Standalone (no dependencies): http://localhost:8080/demo/standalone.html
• ESM (module import): http://localhost:8080/demo/esm.html

Installation

Install via npm (for ESM/CJS consumption):

npm install meridian-halo three

Or include via script tags (no install required): see Browser usage below.

Usage

ESM (recommended)

import * as MeridianHalo from 'meridian-halo';

const mount = document.getElementById('app')!;
const halo = MeridianHalo.createHalo({ mount, width: 512, height: 512 });

// later
halo.destroy();

CJS (Node/CommonJS)

const MeridianHalo = require('meridian-halo');
const mount = document.getElementById('app');
const halo = MeridianHalo.createHalo({ mount, width: 512, height: 512 });

Browser (external Three)

<div id="app"></div>
<script src="https://unpkg.com/three@0.160.0/build/three.min.js"></script>
<script src="/dist/meridian-halo.min.js"></script>
<script>
  const mount = document.getElementById('app');
  const halo = MeridianHalo.createHalo({ mount, width: 512, height: 512 });
</script>

Note: Three’s "build/three.min.js" logs a deprecation warning but works. For a fully modern path, use the ESM demo which imports build/three.module.js.

Browser (standalone, no dependencies)

<div id="app"></div>
<script src="/dist/meridian-halo.standalone.min.js"></script>
<script>
  const halo = MeridianHalo.createHalo({ mount: document.getElementById('app'), width: 512, height: 512 });
</script>

API

createHalo(options: HaloOptions): HaloIcon

Creates and mounts a halo instance. Returns methods for control and cleanup.

destroyHalo(icon: HaloIcon): void

Convenience wrapper to dispose the instance.

HaloIcon

• setBrightness(scale: number): void
• setMode(mode: 'always-bright' | 'auto'): void
• setBG(hex: string | null): void
• setStyleCycle(enabled: boolean): void
• destroy(): void
• three: { scene: THREE.Scene; renderer: THREE.Renderer; camera: THREE.Camera }

HaloOptions (partial)

• mount: HTMLElement (required)
• width, height: number — canvas size in CSS pixels
• count: number — total particles (outer + inner)
• radius: number — base radius of the halo sphere
• initialSpeed: number — initial tangential velocity scalar
• pointSize: number — base point size
• physics: { gravityStrength, tangentialStrength, springK, damping, maxVel }
• swoosh: { minInterval, maxInterval, duration, amplitude, groupRadius, accentBoost }
• palettes: { neutralCool, deepTech, warmEthereal }
• mood: { cyclePeriod, ethereal, energetic }
• styleCycle: { enabled, period }
• mode: 'always-bright' | 'auto'

Defaults are defined in src/config.ts and merged with your options.

Notes

• Rendering: Uses a simple Three.js scene with a single Group and two Points meshes (outer/inner).
• Performance: Uses typed arrays and in-place updates; geometry attributes are marked dynamic and updated per frame.
• Browser bundles:
  • dist/meridian-halo.min.js: expects window.THREE (external three). Small and flexible.
  • dist/meridian-halo.standalone.min.js: includes Three.js for zero-dependency drop-in. Heavier.
• ESM/CJS builds for modern bundlers:
  • dist/meridian-halo.mjs (ESM)
  • dist/meridian-halo.cjs (CommonJS)

Development

Build:

npm run build

Watch:

npm run dev

Serve demos:

npm run demo:serve

Release

CI will build and attach artifacts when you push a tag starting with v (e.g., v0.1.0).

Local release helper (uses gh):

# 1) bump package.json version first (e.g., 0.1.0)
# 2) commit your changes
npm run release

This will build, create an annotated tag v<version>, push tags, and create a GitHub Release with artifacts.

---

Licensed under MIT.