Event Horizon Laboratory

An interactive dot matrix black hole simulation and real exoplanet atlas built with React, Three.js, Vinext, and Cloudflare Workers.

Open the live laboratory

What this is

Event Horizon Laboratory is a browser based scientific visual experience with two connected instruments.

1. Field Mode renders an expressive particle simulation inspired by matter orbiting a rotating black hole.

2. Atlas Mode searches confirmed planetary systems, enriches them with Gaia astrometry, and renders their orbital architecture in three dimensions.

The goal is not to pretend every visual is a direct observation. The interface explicitly separates catalogued measurements, computed estimates, and artistic geometry.

What you can do

1. Change black hole mass, spin, particle density, emission, time scale, lensing, and relativistic beaming.

2. Orbit, zoom, reset, and capture the Three.js scene.

3. Search real confirmed exoplanet systems through NASA PSCompPars.

4. Inspect Gaia DR3 position, parallax, proper motion, radial velocity, magnitude, and colour when a matching identifier is available.

5. Enter Mission Mode for a guided journey from Earth to Proxima Centauri, TRAPPIST 1, and TOI 700.

6. Follow a five step overlay walkthrough on the first visit, or replay it from the question mark control.

7. Keep exploring when NASA or Gaia is unavailable through the versioned local catalog snapshot.

Start locally

Requirements:

1. Node.js 22.13 or newer

2. npm

3. Linux for the included bounded build scripts

git clone https://github.com/ruvnet/Event-Horizon.git
cd Event-Horizon
npm ci
npm run dev

Then open the local address printed by Vite.

Run the production checks:

npm run lint
npm test

The test command builds the Cloudflare Worker output and verifies the root route, catalog validation, offline fallback, Three.js runtime boundary, Mission Mode, and overlay walkthrough.

How the real data path works

The browser never receives a general catalog proxy.

Browser search
      ↓
Fixed server route at /api/astro
      ↓
NASA Exoplanet Archive PSCompPars
      ↓
Optional Gaia DR3 enrichment
      ↓
Normalized StarSystem response
      ↓
Three.js Atlas or local snapshot fallback

The server accepts only a validated system name. It owns the endpoint, table, selected fields, ordering, row limit, redirect policy, timeout, and response size cap. Users cannot submit a URL, table name, column list, or ADQL fragment.

Understanding the evidence labels

Catalogued

A value returned by NASA PSCompPars or Gaia DR3, or preserved in the versioned fallback snapshot.

Examples include right ascension, declination, distance, stellar temperature, orbital period, planet radius, and planet mass.

Computed

A value derived from catalogued inputs.

For example, when a semi major axis is unavailable but period and stellar mass exist, the interface can estimate orbital scale using Kepler's third law.

Artistic

Geometry chosen to make an incomplete system understandable.

Most exoplanets do not have enough published orbital elements to reconstruct current three dimensional position. Missing orientation and instantaneous phase therefore use deterministic artistic values and remain labelled as such.

Architecture

The application keeps rendering and external data isolated.

1. app/page.tsx owns Field Mode, shared laboratory controls, dialogs, administrative settings, and the walkthrough overlay.

2. app/atlas-mode.tsx owns Atlas Mode, Mission Mode, system navigation, provenance presentation, and its browser only Three.js scene.

3. app/api/astro/route.ts owns the bounded NASA and Gaia query templates, validation, normalization, timeouts, caching headers, and fallback behavior.

4. app/astro/catalog.ts defines the normalized catalog contract and versioned featured systems.

5. worker/index.ts adapts Vinext output to the Cloudflare Worker runtime.

6. tests/rendered-html.test.mjs exercises Worker compatibility and the critical security invariants.

Read the deeper architecture guide and architecture decision records.

Three.js Worker safety

Three.js and OrbitControls are loaded only inside browser effects through dynamic imports. Nothing creates a renderer, clock, control object, texture, or scene at Worker module scope.

This boundary prevents server rendering and Cloudflare Worker startup from evaluating browser only Three.js code. A source invariant test protects the rule.

Performance targets

1. Atlas background stars: 8,000 on mobile and 18,000 on desktop.

2. Device pixel ratio ceiling: 1.25 on mobile and 1.5 on desktop.

3. Catalog response cap: 900,000 bytes.

4. Upstream timeout: 4 seconds for each bounded catalog request.

5. Root route: independent from NASA, Gaia, and Three.js initialization.

6. Offline featured system load: local and immediate.

Data sources

1. NASA Exoplanet Archive using the composite PSCompPars table

2. ESA Gaia Archive using Gaia DR3

PSCompPars is a composite table. Values for different fields may originate from different publications and are not guaranteed to form a single self consistent orbital solution.

Project structure

app/
  api/astro/route.ts       Bounded catalog service
  astro/catalog.ts         Types and fallback systems
  atlas-mode.tsx           Atlas and Mission experiences
  globals.css              Complete instrument visual system
  layout.tsx               Metadata and document shell
  page.tsx                 Field experience and shared controls
docs/
  adr/                     Architecture decisions
  images/                  Repository media
tests/
  rendered-html.test.mjs   Worker and security acceptance checks
worker/
  index.ts                 Cloudflare Worker entry point

Security model

The main operational risk is turning the catalog route into an anonymous TAP relay. The implementation prevents that by fixing both upstream hosts and query templates, validating all names, limiting rows, rejecting redirects, enforcing timeouts, capping response bodies, and never accepting arbitrary ADQL.

The application contains no catalog credentials. Local preferences and walkthrough completion stay in browser storage. See SECURITY.md for the full boundary and reporting guidance.

Known limits

1. Field Mode is an expressive parametric model, not a numerical general relativity solver.

2. Exoplanet orientation and current phase are often unknown.

3. The local snapshot contains selected showcase systems rather than the entire NASA or Gaia catalog.

4. Live system detail depends on public archive availability and quota policy.

5. The repository currently has no software license. Public visibility does not itself grant reuse rights.

Deployment

The production application runs as a Vinext application compiled to a Cloudflare Worker compatible bundle.

npm run build
npm run start

The checked build produces dist/server/index.js with a default Worker object exposing fetch(request, env, ctx).

The repository includes .openai/hosting.example.json rather than the live Site identity. Copy it to .openai/hosting.json only when attaching your own Sites project.

Documentation

1. Architecture

2. Data provenance

3. Security policy

4. ADR 0001: Browser only Three.js runtime

5. ADR 0002: Bounded astronomy catalog service

6. ADR 0003: Evidence classes and deterministic fallback

7. ADR 0004: Guided missions and local walkthrough state

Contributing

Keep changes scientifically honest and operationally bounded.

1. Preserve the browser only Three.js import invariant.

2. Do not add a general upstream proxy or user supplied ADQL.

3. Preserve null values as unknown rather than converting them to zero.

4. Label every derived or illustrative value.

5. Add or update an acceptance check for every new trust boundary.

6. Run npm run lint and npm test before proposing a change.

Live project

Launch Event Horizon Laboratory