# Integrate `UmbralOrrery` from Motion Garden

You are helping me add the **UmbralOrrery** component to an existing project.
Everything you need is below — full source, dependencies, props and the
behavioural contract. Read it all before writing anything.

- **Component:** UmbralOrrery
- **Category:** Power-User Systems
- **Summary:** A planet, its moons and their sun, drawn by one ray-traced shader. Each moon casts a real eclipse shadow on the planet, dark in the middle and soft at the edge. A moon turns ember red when it passes into the planet's own shadow. Drag to move the camera around to the night side, where the atmosphere lights up as a ring.
- **Reference:** https://motion-garden.netlify.app/components/umbral-orrery
- **Full catalog (for you, the agent):** https://motion-garden.netlify.app/llms.txt

## Stack this source assumes

- React 19 with the Next.js App Router (never the `pages/` directory)
- TypeScript, strict
- Tailwind CSS v4, CSS-first config (utilities are inline; no `tailwind.config` needed)

If my project differs, adapt the integration — but do not rewrite the animation math to suit a different stack. Ask me first.

## Dependencies

```bash
bun add ogl
```

## Files to create

2 files — all of them are required. Paths are as shipped; the component may live anywhere in my project, but keep every peer file at the exact path shown so the import aliases resolve.

### 1. `components/registry/umbral-orrery/umbral-orrery.tsx`

```tsx
"use client";

import { memo, useEffect, useRef, useState } from "react";
import { Renderer, Program, Mesh, Triangle } from "ogl";
import { useAnimationLoop, type Metrics } from "@/hooks/use-animation-loop";

export interface UmbralOrreryProps {
  moonCount?: number;
  orbitSpeed?: number;
  tilt?: number;
  moonSize?: number;
  sunSize?: number;
  sunIntensity?: number;
  atmosphere?: number;
  trails?: number;
  drift?: number;
  zoom?: number;
  sunColor?: string;
  glowColor?: string;
  planetColor?: string;
  backgroundColor?: string;
  paused?: boolean;
  className?: string;
}

const MOONS = 6;
const TAU = Math.PI * 2;
const CAMERA_DISTANCE = 11;
const ORBIT_INNER = 1.75;
const ORBIT_STEP = 0.46;
const PITCH_LIMIT = 1.35;
const HALF_FOV_TAN = 0.384;

const ORBITS = [
  { phase: 2.82, lean: 0.0, miss: 0.18, size: 1.0 },
  { phase: 1.0, lean: 0.22, miss: -0.42, size: 0.72 },
  { phase: 5.25, lean: -0.16, miss: 0.5, size: 1.28 },
  { phase: 2.3, lean: 0.3, miss: -0.1, size: 0.6 },
  { phase: 4.3, lean: -0.27, miss: 0.34, size: 0.95 },
  { phase: 0.2, lean: 0.12, miss: -0.55, size: 0.8 },
];

const hexToRgb = (hex: string): [number, number, number] => {
  const h = hex.replace("#", "");
  const full = h.length === 3 ? h.split("").map((c) => c + c).join("") : h;
  const n = parseInt(full, 16);
  if (Number.isNaN(n) || full.length !== 6) return [1, 1, 1];
  return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];
};

const setLinear = (out: Float32Array, hex: string) => {
  const [r, g, b] = hexToRgb(hex);
  out[0] = Math.pow(r, 2.2);
  out[1] = Math.pow(g, 2.2);
  out[2] = Math.pow(b, 2.2);
};

const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));

const supportsWebGL2 = () => {
  try {
    return !!document.createElement("canvas").getContext("webgl2");
  } catch {
    return false;
  }
};

const vertex = `#version 300 es
in vec2 position;
void main() {
  gl_Position = vec4(position, 0.0, 1.0);
}`;

const fragment = `#version 300 es
precision highp float;
out vec4 fragColor;

#define MOONS 6
#define TAU 6.28318530718

uniform vec2  uRes;
uniform float uDpr;
uniform vec3  uCamPos;
uniform vec3  uCamRight;
uniform vec3  uCamUp;
uniform vec3  uCamFwd;
uniform float uFocal;
uniform float uCount;
uniform vec4  uMoon[MOONS];
uniform vec4  uOrbU[MOONS];
uniform vec4  uOrbV[MOONS];
uniform float uSunSize;
uniform float uSunPower;
uniform float uAtmo;
uniform float uTrails;
uniform vec2  uSpin;
uniform vec3  uSunCol;
uniform vec3  uGlowCol;
uniform vec3  uPlanetCol;
uniform vec3  uBg;

const vec3 SUN_POS = vec3(-90.0, 0.0, 0.0);
const vec3 SUN_DIR = vec3(-1.0, 0.0, 0.0);

const vec3 MOON_TINT[MOONS] = vec3[](
  vec3(0.62, 0.60, 0.58),
  vec3(0.50, 0.55, 0.64),
  vec3(0.68, 0.56, 0.42),
  vec3(0.66, 0.60, 0.72),
  vec3(0.72, 0.69, 0.62),
  vec3(0.60, 0.44, 0.38)
);

// Angular size of one buffer pixel, set once per fragment.
float gPx;

float hash13(vec3 p) {
  p = fract(p * 0.1031);
  p += dot(p, p.zyx + 31.32);
  return fract((p.x + p.y) * p.z);
}

vec3 hash33(vec3 p) {
  p = fract(p * vec3(0.1031, 0.1030, 0.0973));
  p += dot(p, p.yxz + 33.33);
  return fract((p.xxy + p.yxx) * p.zyx);
}

float noise(vec3 p) {
  vec3 i = floor(p);
  vec3 f = fract(p);
  f = f * f * (3.0 - 2.0 * f);
  float a = mix(hash13(i), hash13(i + vec3(1, 0, 0)), f.x);
  float b = mix(hash13(i + vec3(0, 1, 0)), hash13(i + vec3(1, 1, 0)), f.x);
  float c = mix(hash13(i + vec3(0, 0, 1)), hash13(i + vec3(1, 0, 1)), f.x);
  float d = mix(hash13(i + vec3(0, 1, 1)), hash13(i + vec3(1, 1, 1)), f.x);
  return mix(mix(a, b, f.y), mix(c, d, f.y), f.z);
}

float fbm(vec3 p, int octaves) {
  float amp = 0.5;
  float sum = 0.0;
  for (int i = 0; i < octaves; i++) {
    sum += amp * noise(p);
    p = p * 2.03 + 11.7;
    amp *= 0.5;
  }
  return sum;
}

// How much of the sun's disc is still visible from p past a sphere. Both are
// discs in p's sky: a is the sun's angular radius, b the sphere's, d the angle
// between their centres. No overlap is full light, full overlap is the umbra,
// and a sphere smaller than the sun can only ever hide (b/a)^2 of it.
float sunVisible(vec3 p, vec3 c, float r) {
  vec3 toSun = normalize(SUN_POS - p);
  vec3 toC = c - p;
  float dc = length(toC);
  if (dc <= r) return 1.0;
  toC /= dc;
  float a = uSunSize;
  float b = asin(r / dc);
  // atan of cross and dot, not acos of dot: acos loses all its precision
  // exactly where the two discs line up, which is the moment that matters.
  float d = atan(length(cross(toSun, toC)), dot(toSun, toC));
  float cover = min(1.0, (b * b) / (a * a));
  return 1.0 - cover * (1.0 - smoothstep(abs(b - a), a + b, d));
}

float shadow(vec3 p, int self) {
  float vis = self == 0 ? 1.0 : sunVisible(p, vec3(0.0), 1.0);
  for (int i = 0; i < MOONS; i++) {
    if (float(i) >= uCount) break;
    if (i + 1 == self) continue;
    vis *= sunVisible(p, uMoon[i].xyz, uMoon[i].w);
  }
  return vis;
}

// Sphere grown by half a pixel. cov is how much of the pixel the true sphere
// fills, so the silhouette can be blended instead of stair-stepped.
float sphere(vec3 ro, vec3 rd, vec3 c, float r, out float cov) {
  vec3 oc = ro - c;
  float tc = -dot(oc, rd);
  cov = 0.0;
  if (tc <= 0.0) return -1.0;
  float d2 = max(dot(oc, oc) - tc * tc, 0.0);
  float w = gPx * tc;
  float grown = r + 0.5 * w;
  if (d2 >= grown * grown) return -1.0;
  cov = clamp((grown - sqrt(d2)) / w, 0.0, 1.0);
  return tc - sqrt(grown * grown - d2);
}

// id: -1 sky, 0 planet, 1.. moons.
void trace(vec3 ro, vec3 rd, int skip, out int id, out float t, out float cov) {
  id = -1;
  t = 1e9;
  cov = 1.0;
  float c;
  if (skip != 0) {
    float tp = sphere(ro, rd, vec3(0.0), 1.0, c);
    if (tp > 0.0) { id = 0; t = tp; cov = c; }
  }
  for (int i = 0; i < MOONS; i++) {
    if (float(i) >= uCount) break;
    if (i + 1 == skip) continue;
    float tm = sphere(ro, rd, uMoon[i].xyz, uMoon[i].w, c);
    if (tm > 0.0 && tm < t) { id = i + 1; t = tm; cov = c; }
  }
}

vec3 sunLight() {
  return mix(vec3(1.0), uSunCol, 0.4) * uSunPower;
}

vec3 atmoLight(vec3 n, vec3 rd) {
  float day = smoothstep(-0.25, 0.5, dot(n, SUN_DIR));
  // Looking toward the sun through the limb: the air scatters forward, which
  // is what lights the whole ring when the planet eclipses the sun.
  float fwd = pow(max(dot(rd, SUN_DIR), 0.0), 6.0);
  vec3 c = uGlowCol * (0.03 + 0.85 * day);
  c += mix(uGlowCol, uSunCol, 0.55) * fwd * 3.0;
  return c * uAtmo;
}

vec3 planetAlbedo(vec3 n) {
  n.xy = mat2(0.94, -0.342, 0.342, 0.94) * n.xy;
  // Rigid spin, passed as a cos/sin pair so the angle can wrap without the
  // noise field jumping at the seam.
  n.xz = mat2(uSpin.x, -uSpin.y, uSpin.y, uSpin.x) * n.xz;
  float lat = n.y;
  float warp = fbm(n * 2.3 + 4.0, 4);
  float swirl = fbm(vec3(n.x * 3.0, lat * 9.0, n.z * 3.0) + warp * 1.8, 5);
  float bands = sin(lat * 11.0 + (warp - 0.5) * 3.4 + swirl * 2.2);
  bands = 0.72 * bands + 0.28 * sin(lat * 27.0 + swirl * 5.0 + warp * 2.0);
  float fine = fbm(vec3(n.x * 6.0, lat * 34.0, n.z * 6.0) + swirl * 2.5, 4);
  vec3 deep = uPlanetCol * 0.4;
  vec3 mid = uPlanetCol * 1.5 + 0.012;
  vec3 pale = mix(uPlanetCol * 2.6, vec3(0.80, 0.74, 0.92), 0.38);
  vec3 col = mix(deep, mid, smoothstep(-0.7, 0.5, bands));
  col = mix(col, pale, smoothstep(0.15, 1.0, bands) * (0.2 + 0.6 * fine));
  col *= 0.7 + 0.6 * fine;
  col *= 1.0 - 0.4 * smoothstep(0.55, 1.0, abs(lat));
  return col;
}

vec3 shadePlanet(vec3 p, vec3 rd) {
  vec3 n = normalize(p);
  float ndl = dot(n, normalize(SUN_POS - p));
  vec3 alb = planetAlbedo(n);
  float vis = ndl > -0.3 ? shadow(p, 0) : 1.0;
  float diff = smoothstep(-0.04 - uSunSize, 0.3, ndl) * (0.3 + 0.7 * max(ndl, 0.0));
  // Light that reaches the terminator has crossed the most air, so it arrives red.
  vec3 light = sunLight() * mix(vec3(1.0, 0.5, 0.3), vec3(1.0), smoothstep(-0.02, 0.34, ndl));
  vec3 col = alb * light * diff * vis;
  col += alb * uGlowCol * 0.01;
  float fres = pow(1.0 - max(dot(n, -rd), 0.0), 4.5);
  col += atmoLight(n, rd) * fres * mix(1.0, vis, 0.6);
  return col;
}

vec3 shadeMoon(int i, vec3 p, vec3 rd) {
  vec3 c = uMoon[i].xyz;
  float r = uMoon[i].w;
  vec3 n = normalize(p - c);
  vec3 q = n * 2.6 + float(i) * 7.3;
  // Finite-difference bump: tilt the normal down the slope of the same noise
  // that paints the surface, so dark patches read as basins.
  float e = 0.06;
  float h0 = fbm(q, 4);
  vec3 grad = vec3(fbm(q + vec3(e, 0, 0), 4), fbm(q + vec3(0, e, 0), 4), fbm(q + vec3(0, 0, e), 4)) - h0;
  n = normalize(n - (grad - n * dot(grad, n)) * 5.0);
  float maria = smoothstep(0.42, 0.62, fbm(q * 0.7 + 3.1, 3));
  vec3 alb = MOON_TINT[i] * (0.5 + 0.7 * h0) * (1.0 - 0.45 * maria);

  vec3 toSun = normalize(SUN_POS - p);
  float ndl = dot(n, toSun);
  float lit = shadow(p, i + 1);
  float diff = smoothstep(-uSunSize, 0.12, ndl) * pow(max(ndl, 0.0), 0.75);
  vec3 col = alb * sunLight() * diff * lit;

  // Planetshine: the lit face of the planet is a second, dim lamp. A moon on
  // the sun side looks back at all of it, a moon behind the planet at none.
  float dp = length(c);
  vec3 toPlanet = -c / dp;
  float phase = 0.5 - 0.5 * dot(toPlanet, SUN_DIR);
  float bounce = max(dot(n, toPlanet), 0.0) * phase / (dp * dp);
  col += alb * mix(uPlanetCol * 2.0 + 0.1, uGlowCol, 0.35) * bounce * uSunPower * 0.7;

  // Inside the planet's shadow the only sunlight left is what its atmosphere
  // bends around the limb, and that light is ember red.
  float inPlanetShadow = 1.0 - sunVisible(p, vec3(0.0), 1.0);
  col += alb * uSunCol * vec3(1.0, 0.3, 0.14) * inPlanetShadow * max(ndl, 0.0) * 0.07 * uSunPower * uAtmo;
  return col;
}

vec3 sky(vec3 rd) {
  vec3 col = vec3(0.0);

  // A wide view takes in far more sky, so it shows a smaller share of the
  // stars and the count on screen holds steady. Zooming in brings the rest
  // out the way a longer lens would, without reshuffling the field.
  float keep = clamp(uFocal * uFocal / 15.0, 0.06, 1.0);
  for (int k = 0; k < 2; k++) {
    float scale = k == 0 ? 52.0 : 17.0;
    vec3 id = floor(rd * scale);
    vec3 h = hash33(id + float(k) * 31.7);
    if (fract(h.y * 13.7 + h.x * 5.3) > keep) continue;
    vec3 s = normalize(id + 0.5 + (h - 0.5) * 0.7);
    float d = length(rd - s);
    float r = gPx * uDpr * (k == 0 ? 0.75 : 1.15);
    // Most stars are faint and a few are not: a steep power on the hash is
    // what keeps the field from reading as evenly scattered snow.
    float mag = fract(h.x * 7.13 + h.z * 3.71);
    float bright = k == 0 ? 0.02 + 0.55 * pow(mag, 6.0) : 0.05 + 1.6 * pow(mag, 4.0);
    vec3 tint = mix(vec3(0.72, 0.82, 1.0), vec3(1.0, 0.86, 0.72), h.y);
    col += tint * bright * smoothstep(r * 1.6, r * 0.2, d);
  }

  float cloud = fbm(rd * 1.7 + 2.0, 4);
  float knot = fbm(rd * 4.1 - 7.0, 3);
  float dust = smoothstep(0.42, 0.8, cloud) * (0.35 + 0.65 * knot);
  col += mix(uGlowCol, uSunCol * 0.6, knot * 0.7) * dust * 0.03;

  vec3 sd = normalize(SUN_POS - uCamPos);
  float th = atan(length(cross(rd, sd)), dot(rd, sd));
  float x = th / uSunSize;
  float disc = 1.0 - smoothstep(1.0 - 2.0 * gPx / uSunSize, 1.0, x);
  float mu = sqrt(max(1.0 - x * x, 0.0));
  // Limb darkening: the edge of the disc is seen through more of the sun, so
  // it is dimmer and redder than the centre. Without it the sun is a flat coin.
  col += mix(uSunCol * 1.1, vec3(1.0, 0.96, 0.88), pow(mu, 0.7)) * (0.3 + 0.7 * mu) * uSunPower * 3.6 * disc;

  // The corona belongs to the sky, not the lens: a body in front of the sun
  // hides the disc but leaves the streamers standing around its edge.
  if (x < 9.0) {
    vec3 e1 = normalize(cross(sd, vec3(0.0, 1.0, 0.0)));
    vec3 e2 = cross(sd, e1);
    float ang = atan(dot(rd, e2), dot(rd, e1));
    float streamer = fbm(vec3(cos(ang), sin(ang), 0.3) * 3.2 + x * 0.1, 4);
    float corona = exp(-max(x - 1.0, 0.0) * 1.15) * (0.3 + 1.6 * streamer * streamer);
    col += uSunCol * corona * uSunPower * 0.6 * (1.0 - disc) * (1.0 - smoothstep(7.0, 9.0, x));
  }
  return col;
}

// Air outside the limb, for rays that pass the planet without touching it.
vec3 halo(vec3 ro, vec3 rd, float tMax) {
  float tc = -dot(ro, rd);
  if (tc <= 0.0 || tc > tMax) return vec3(0.0);
  vec3 pc = ro + rd * tc;
  float b = length(pc);
  float h = max(b - 1.0, 0.0);
  float fall = 0.88 * exp(-h / (0.022 + 0.014 * uAtmo)) + 0.12 * exp(-h / 0.2);
  return atmoLight(pc / b, rd) * fall;
}

vec3 trails(vec3 ro, vec3 rd, float tMax) {
  vec3 acc = vec3(0.0);
  if (uTrails <= 0.0) return acc;
  for (int i = 0; i < MOONS; i++) {
    if (float(i) >= uCount) break;
    vec3 U = uOrbU[i].xyz;
    vec3 V = uOrbV[i].xyz;
    vec3 N = cross(U, V);
    float dn = dot(rd, N);
    if (abs(dn) < 1e-4) continue;
    float t = -dot(ro, N) / dn;
    if (t <= 0.0 || t >= tMax) continue;
    vec3 q = ro + rd * t;
    vec2 pl = vec2(dot(q, U), dot(q, V));
    float rad = length(pl);
    float d = abs(rad - uOrbU[i].w);
    // Distance to the ring measured on screen, so the trace holds one pixel of
    // width whether its plane is seen face on or nearly edge on.
    vec3 er = (U * pl.x + V * pl.y) / max(rad, 1e-4);
    float px = d * length(er - rd * dot(er, rd)) / (gPx * t);
    float line = 1.0 - smoothstep(0.6 * uDpr, 1.7 * uDpr, px);
    line *= 1.0 - smoothstep(0.03, 0.09, d);
    line *= smoothstep(0.012, 0.07, abs(dn));
    // Brightest at the moon, fading back along the lap it has just flown.
    float behind = mod(uOrbV[i].w - atan(pl.y, pl.x), TAU) / TAU;
    float fade = 0.07 + 0.93 * pow(1.0 - behind, 3.0);
    acc += mix(uGlowCol, vec3(1.0), 0.45) * line * fade * 0.55;
  }
  return acc * uTrails;
}

vec4 surface(vec3 ro, vec3 rd, int id, float t) {
  if (id == 0) return vec4(shadePlanet(ro + rd * t, rd), 0.0);
  vec3 col;
  float open;
  if (id > 0) {
    col = shadeMoon(id - 1, ro + rd * t, rd);
    open = 0.0;
  } else {
    col = sky(rd);
    open = 1.0;
  }
  col += halo(ro, rd, t);
  return vec4(col, open);
}

vec3 aces(vec3 x) {
  return clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), 0.0, 1.0);
}

void main() {
  vec2 p = (gl_FragCoord.xy * 2.0 - uRes) / uRes.y;
  vec3 ro = uCamPos;
  vec3 rd = normalize(uCamFwd * uFocal + uCamRight * p.x + uCamUp * p.y);
  gPx = 2.0 / (uRes.y * uFocal);

  int id;
  float t;
  float cov;
  trace(ro, rd, -1, id, t, cov);
  vec4 c = surface(ro, rd, id, t);
  if (id >= 0 && cov < 1.0) {
    int id2;
    float t2;
    float cov2;
    trace(ro, rd, id, id2, t2, cov2);
    c = mix(surface(ro, rd, id2, t2), c, cov);
  }
  vec3 col = c.rgb;
  col += trails(ro, rd, t);

  // Lens bloom, scaled by how much of the sun the camera itself can see, so it
  // drains away as the sun slides behind the planet instead of popping off.
  float seen = sunVisible(ro, vec3(0.0), 1.0);
  for (int i = 0; i < MOONS; i++) {
    if (float(i) >= uCount) break;
    seen *= sunVisible(ro, uMoon[i].xyz, uMoon[i].w);
  }
  vec3 sd = normalize(SUN_POS - ro);
  float th = atan(length(cross(rd, sd)), dot(rd, sd));
  float bloom = 0.045 / (1.0 + th * th * 90.0) + 0.4 * exp(-th / (uSunSize * 1.8));
  // A body in front of the glare keeps most of its silhouette: full bloom over
  // open sky, a quarter of it over anything solid.
  col += uSunCol * bloom * seen * uSunPower * mix(0.25, 1.0, c.a);

  col = pow(aces(col), vec3(1.0 / 2.2));
  // The backdrop goes in after tone mapping and only where the sky is open, so
  // it comes out as the exact colour that was asked for.
  col = 1.0 - (1.0 - col) * (1.0 - uBg * c.a);
  col += (hash13(vec3(gl_FragCoord.xy, 1.0)) - 0.5) / 255.0;
  fragColor = vec4(col, 1.0);
}`;

const UmbralOrrery = memo(
  ({
    moonCount = 4,
    orbitSpeed = 1,
    tilt = 0.3,
    moonSize = 0.2,
    sunSize = 0.05,
    sunIntensity = 1.6,
    atmosphere = 1,
    trails = 0.6,
    drift = 0.03,
    zoom = 1.5,
    sunColor = "#ffb24d",
    glowColor = "#a855f7",
    planetColor = "#4b3a8c",
    backgroundColor = "#05060a",
    paused = false,
    className,
  }: UmbralOrreryProps) => {
    const containerRef = useRef<HTMLDivElement>(null);
    const drawRef = useRef<((dt: number) => void | false) | null>(null);
    const measureRef = useRef<((m: Metrics) => void) | null>(null);
    const glRef = useRef<WebGLRenderingContext | WebGL2RenderingContext | null>(null);
    const orbit = useRef({
      yaw: -0.85, pitch: 0.22, vYaw: 0, vPitch: 0,
      dragging: false, pointerId: -1, lastX: 0, lastY: 0, lastT: 0,
    });

    const [fallback, setFallback] = useState(false);

    const loop = useAnimationLoop({
      target: containerRef,
      halted: paused,
      dpr: 2,
      onResize: (metrics) => measureRef.current?.(metrics),
      onFrame: ({ dt }) => (drawRef.current ? drawRef.current(dt) : false),
      gl: () => glRef.current,
    });

    const live = useRef({
      moonCount, orbitSpeed, tilt, moonSize, sunSize, sunIntensity, atmosphere,
      trails, drift, zoom, sunColor, glowColor, planetColor, backgroundColor,
    });
    live.current = {
      moonCount, orbitSpeed, tilt, moonSize, sunSize, sunIntensity, atmosphere,
      trails, drift, zoom, sunColor, glowColor, planetColor, backgroundColor,
    };

    useEffect(() => {
      const container = containerRef.current;
      if (fallback || !container) return;
      if (!supportsWebGL2()) {
        setFallback(true);
        return;
      }

      const renderer = new Renderer({
        webgl: 2,
        alpha: false,
        antialias: false,
        powerPreference: "high-performance",
        dpr: 1,
      });
      const gl = renderer.gl;
      glRef.current = gl;

      const canvas = gl.canvas as HTMLCanvasElement;
      canvas.style.display = "block";
      canvas.style.position = "absolute";
      canvas.style.top = "0";
      canvas.style.left = "0";
      container.appendChild(canvas);

      const moon: number[] = new Array(MOONS * 4).fill(0);
      const orbU: number[] = new Array(MOONS * 4).fill(0);
      const orbV: number[] = new Array(MOONS * 4).fill(0);

      const uniforms = {
        uRes: { value: new Float32Array([1, 1]) },
        uDpr: { value: 1 },
        uCamPos: { value: new Float32Array(3) },
        uCamRight: { value: new Float32Array(3) },
        uCamUp: { value: new Float32Array(3) },
        uCamFwd: { value: new Float32Array(3) },
        uFocal: { value: 1 },
        uCount: { value: 1 },
        uMoon: { value: moon },
        uOrbU: { value: orbU },
        uOrbV: { value: orbV },
        uSunSize: { value: sunSize },
        uSunPower: { value: sunIntensity },
        uAtmo: { value: atmosphere },
        uTrails: { value: trails },
        uSpin: { value: new Float32Array([1, 0]) },
        uSunCol: { value: new Float32Array(3) },
        uGlowCol: { value: new Float32Array(3) },
        uPlanetCol: { value: new Float32Array(3) },
        uBg: { value: new Float32Array(3) },
      };

      const program = new Program(gl, { vertex, fragment, uniforms });
      const mesh = new Mesh(gl, { geometry: new Triangle(gl), program });

      const angles = ORBITS.map((o) => o.phase);
      let spin = 0;
      let aspect = 1;

      const renderAll = () => {
        const l = live.current;
        const o = orbit.current;

        for (let i = 0; i < MOONS; i++) {
          const s = ORBITS[i];
          const R = ORBIT_INNER + i * ORBIT_STEP;
          const lean = l.tilt + s.lean;
          const vy = Math.sin(lean);
          const vz = Math.cos(lean);
          const sd = s.miss / R;
          const cd = Math.sqrt(1 - sd * sd);
          const ux = cd;
          const uy = -vz * sd;
          const uz = vy * sd;
          const ca = Math.cos(angles[i]);
          const sa = Math.sin(angles[i]);
          const k = i * 4;
          moon[k] = R * ca * ux;
          moon[k + 1] = R * (ca * uy + sa * vy);
          moon[k + 2] = R * (ca * uz + sa * vz);
          moon[k + 3] = l.moonSize * s.size;
          orbU[k] = ux;
          orbU[k + 1] = uy;
          orbU[k + 2] = uz;
          orbU[k + 3] = R;
          orbV[k] = 0;
          orbV[k + 1] = vy;
          orbV[k + 2] = vz;
          orbV[k + 3] = angles[i];
        }

        const cp = Math.cos(o.pitch);
        const sp = Math.sin(o.pitch);
        const cy = Math.cos(o.yaw);
        const sy = Math.sin(o.yaw);
        const dx = sy * cp;
        const dy = sp;
        const dz = cy * cp;
        uniforms.uCamPos.value.set([dx * CAMERA_DISTANCE, dy * CAMERA_DISTANCE, dz * CAMERA_DISTANCE]);
        uniforms.uCamFwd.value.set([-dx, -dy, -dz]);
        uniforms.uCamRight.value.set([cy, 0, -sy]);
        uniforms.uCamUp.value.set([-sy * sp, cp, -cy * sp]);
        uniforms.uFocal.value = (Math.max(l.zoom, 0.1) / HALF_FOV_TAN) * Math.min(1, aspect / 1.1);

        uniforms.uCount.value = clamp(Math.round(l.moonCount), 1, MOONS);
        uniforms.uSunSize.value = clamp(l.sunSize, 0.004, 0.3);
        uniforms.uSunPower.value = l.sunIntensity;
        uniforms.uAtmo.value = l.atmosphere;
        uniforms.uTrails.value = l.trails;
        uniforms.uSpin.value[0] = Math.cos(spin);
        uniforms.uSpin.value[1] = Math.sin(spin);
        setLinear(uniforms.uSunCol.value, l.sunColor);
        setLinear(uniforms.uGlowCol.value, l.glowColor);
        setLinear(uniforms.uPlanetCol.value, l.planetColor);
        uniforms.uBg.value.set(hexToRgb(l.backgroundColor));

        renderer.render({ scene: mesh });
      };

      drawRef.current = (dt) => {
        const l = live.current;
        const o = orbit.current;
        if (!o.dragging) {
          o.yaw += o.vYaw * dt + l.drift * dt;
          o.pitch = clamp(o.pitch + o.vPitch * dt, -PITCH_LIMIT, PITCH_LIMIT);
          const decay = Math.pow(0.92, dt * 60);
          o.vYaw *= decay;
          o.vPitch *= decay;
        }
        o.yaw %= TAU;
        for (let i = 0; i < MOONS; i++) {
          const R = ORBIT_INNER + i * ORBIT_STEP;
          const omega = 0.55 * Math.pow(ORBIT_INNER / R, 1.5);
          angles[i] = (angles[i] + omega * l.orbitSpeed * dt) % TAU;
        }
        spin = (spin + 0.05 * l.orbitSpeed * dt) % TAU;
        renderAll();
      };

      measureRef.current = ({ width, height, dpr }) => {
        renderer.dpr = dpr;
        renderer.setSize(Math.max(1, Math.floor(width)), Math.max(1, Math.floor(height)));
        uniforms.uRes.value[0] = gl.drawingBufferWidth;
        uniforms.uRes.value[1] = gl.drawingBufferHeight;
        uniforms.uDpr.value = dpr;
        aspect = width / Math.max(height, 1);
        renderAll();
      };

      loop.resize();
      loop.start();

      return () => {
        drawRef.current = null;
        measureRef.current = null;
        if (container.contains(canvas)) container.removeChild(canvas);
      };
      // eslint-disable-next-line react-hooks/exhaustive-deps
    }, [fallback]);

    useEffect(() => {
      loop.paint();
    }, [
      moonCount, orbitSpeed, tilt, moonSize, sunSize, sunIntensity, atmosphere,
      trails, drift, zoom, sunColor, glowColor, planetColor, backgroundColor, loop,
    ]);

    const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
      const o = orbit.current;
      o.dragging = true;
      o.pointerId = e.pointerId;
      o.lastX = e.clientX;
      o.lastY = e.clientY;
      o.lastT = e.timeStamp;
      o.vYaw = 0;
      o.vPitch = 0;
      e.currentTarget.setPointerCapture(e.pointerId);
      loop.start();
    };

    const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
      const o = orbit.current;
      if (!o.dragging || e.pointerId !== o.pointerId) return;
      const dt = (e.timeStamp - o.lastT) / 1000;
      const dYaw = -(e.clientX - o.lastX) * 0.006;
      const dPitch = (e.clientY - o.lastY) * 0.005;
      o.yaw += dYaw;
      o.pitch = clamp(o.pitch + dPitch, -PITCH_LIMIT, PITCH_LIMIT);
      if (dt > 0.001) {
        o.vYaw = dYaw / dt;
        o.vPitch = dPitch / dt;
      }
      o.lastX = e.clientX;
      o.lastY = e.clientY;
      o.lastT = e.timeStamp;
      loop.start();
    };

    const endDrag = (e: React.PointerEvent<HTMLDivElement>) => {
      const o = orbit.current;
      if (o.pointerId !== -1 && e.currentTarget.hasPointerCapture(o.pointerId)) {
        e.currentTarget.releasePointerCapture(o.pointerId);
      }
      if (e.timeStamp - o.lastT > 90) {
        o.vYaw = 0;
        o.vPitch = 0;
      }
      o.dragging = false;
      o.pointerId = -1;
      loop.start();
    };

    if (fallback) {
      return (
        <div
          className={`overflow-hidden ${className ?? "relative h-full w-full"}`}
          style={{
            backgroundColor,
            backgroundImage: `radial-gradient(circle at 50% 50%, transparent 0 17%, ${glowColor}55 17.5%, transparent 21%), radial-gradient(circle at 44% 46%, ${planetColor} 0, #07060d 17%, transparent 17.4%)`,
          }}
        />
      );
    }

    return (
      <div
        ref={containerRef}
        className={`cursor-grab touch-none select-none overflow-hidden active:cursor-grabbing [&_canvas]:touch-none ${className ?? "relative h-full w-full"}`}
        style={{ backgroundColor }}
        onPointerDown={onPointerDown}
        onPointerMove={onPointerMove}
        onPointerUp={endDrag}
        onPointerCancel={endDrag}
      />
    );
  },
);

UmbralOrrery.displayName = "UmbralOrrery";

export default UmbralOrrery;
```

### 2. `hooks/use-animation-loop.ts` — peer hook, required

```tsx
"use client";

import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";

export interface Metrics {
  width: number;
  height: number;
  dpr: number;
  bufferWidth: number;
  bufferHeight: number;
}

export interface FrameInfo {
  now: number;
  dt: number;
  elapsed: number;
  frame: number;
}

export interface AnimationLoopHandle {
  start(): void;
  stop(): void;
  paint(): void;
  resize(): void;
  readonly running: boolean;
}

export interface AnimationLoopOptions {
  target: React.RefObject<HTMLElement | null>;
  halted?: boolean;
  dpr?: number | "auto";
  onResize?(metrics: Metrics): void;
  onFrame?(info: FrameInfo): void | false;
  paintWhenHalted?: boolean;
  resizeDebounceMs?: number;
  gl?(): WebGLRenderingContext | WebGL2RenderingContext | null | undefined;
  onDispose?(): void;
  deps?: unknown[];
}

const MAX_DT = 1 / 15;

export function useAnimationLoop(
  options: AnimationLoopOptions,
): AnimationLoopHandle {
  const opts = useRef(options);
  useLayoutEffect(() => {
    opts.current = options;
  });

  const raf = useRef<number | null>(null);
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
  const running = useRef(false);
  const disposed = useRef(false);
  const startedAt = useRef(0);
  const last = useRef(0);
  const frame = useRef(0);

  const measure = useCallback((): Metrics | null => {
    const el = opts.current.target.current;
    if (!el) return null;
    const rect = el.getBoundingClientRect();
    const cap = opts.current.dpr ?? "auto";
    const limit = cap === "auto" ? 2 : cap;
    const dpr = Math.min(
      typeof window === "undefined" ? 1 : window.devicePixelRatio || 1,
      limit,
    );
    return {
      width: rect.width,
      height: rect.height,
      dpr,
      bufferWidth: Math.max(1, Math.round(rect.width * dpr)),
      bufferHeight: Math.max(1, Math.round(rect.height * dpr)),
    };
  }, []);

  const tick = useCallback(function tick(now: number) {
    if (disposed.current) return;

    if (startedAt.current === 0) startedAt.current = now;
    const dt = last.current === 0 ? 0 : Math.min((now - last.current) / 1000, MAX_DT);
    last.current = now;

    const info: FrameInfo = {
      now,
      dt,
      elapsed: (now - startedAt.current) / 1000,
      frame: frame.current++,
    };

    const verdict = opts.current.onFrame?.(info);

    if (disposed.current) return;

    if (verdict === false || opts.current.halted) {
      running.current = false;
      raf.current = null;
      return;
    }
    raf.current = requestAnimationFrame(tick);
  }, []);

  const start = useCallback(() => {
    if (disposed.current || running.current) return;
    running.current = true;
    last.current = 0;
    raf.current = requestAnimationFrame(tick);
  }, [tick]);

  const stop = useCallback(() => {
    running.current = false;
    if (raf.current !== null) {
      cancelAnimationFrame(raf.current);
      raf.current = null;
    }
  }, []);

  const paint = useCallback(() => start(), [start]);

  const resize = useCallback(() => {
    const metrics = measure();
    if (!metrics) return;
    opts.current.onResize?.(metrics);
    if (opts.current.paintWhenHalted !== false) paint();
    else if (!opts.current.halted) start();
  }, [measure, paint, start]);

  const deps = options.deps ?? [];

  useEffect(() => {
    disposed.current = false;
    const el = opts.current.target.current;
    if (!el) return;

    const run = () => {
      if (disposed.current) return;
      resize();
    };

    const observer = new ResizeObserver(() => {
      const wait = opts.current.resizeDebounceMs ?? 0;
      if (wait <= 0) {
        run();
        return;
      }
      if (timer.current !== null) clearTimeout(timer.current);
      timer.current = setTimeout(() => {
        timer.current = null;
        run();
      }, wait);
    });
    observer.observe(el);

    resize();
    if (!opts.current.halted) start();

    return () => {
      disposed.current = true;
      running.current = false;
      if (raf.current !== null) {
        cancelAnimationFrame(raf.current);
        raf.current = null;
      }
      if (timer.current !== null) {
        clearTimeout(timer.current);
        timer.current = null;
      }
      observer.disconnect();
      opts.current.onDispose?.();
      const context = opts.current.gl?.();
      context?.getExtension("WEBGL_lose_context")?.loseContext();
      startedAt.current = 0;
      last.current = 0;
      frame.current = 0;
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, deps);

  const halted = options.halted ?? false;
  useEffect(() => {
    if (!halted) start();
  }, [halted, start]);

  return useMemo<AnimationLoopHandle>(
    () => ({
      start,
      stop,
      paint,
      resize,
      get running() {
        return running.current;
      },
    }),
    [start, stop, paint, resize],
  );
}
```


## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `moonCount` | `number` | `4` | How many moons orbit the planet. Range 1–6. |
| `orbitSpeed` | `number` | `1` | Speed of every orbit. Inner moons always go around faster than outer ones. Range 0–3 ×. |
| `tilt` | `number` | `0.3` | Turns the orbits around the line from the sun to the planet. Every moon still makes an eclipse at any tilt. Range 0–1.2 rad. |
| `moonSize` | `number` | `0.2` | Size of the moons. The planet's radius is 1. Range 0.08–0.35. |
| `sunSize` | `number` | `0.05` | Size of the sun in the sky. A bigger sun gives softer shadow edges. Range 0.01–0.14 rad. |
| `sunIntensity` | `number` | `1.6` | Brightness of the sunlight. Range 0.3–4. |
| `atmosphere` | `number` | `1` | Strength of the glow around the planet. Range 0–2.5. |
| `trails` | `number` | `0.6` | Brightness of the orbit lines. 0 hides them. Range 0–1.5. |
| `drift` | `number` | `0.03` | How fast the camera circles on its own. 0 keeps it still. Range 0–0.3 rad/s. |
| `zoom` | `number` | `1.5` | How close the view is. Range 0.7–3.5 ×. |
| `sunColor` | `string (hex)` | `"#ffb24d"` | Color of the sun and its light. |
| `glowColor` | `string (hex)` | `"#a855f7"` | Color of the planet's atmosphere. |
| `planetColor` | `string (hex)` | `"#4b3a8c"` | Main color of the planet's cloud bands. |
| `backgroundColor` | `string (hex)` | `"#05060a"` | Color of space behind the scene. |

## Usage

```tsx
import UmbralOrrery from "@/components/registry/umbral-orrery/umbral-orrery";

<UmbralOrrery
  moonCount={4}
  orbitSpeed={1}
  tilt={0.3}
  moonSize={0.2}
  sunSize={0.05}
  sunIntensity={1.6}
  atmosphere={1}
  trails={0.6}
  drift={0.03}
  zoom={1.5}
  sunColor="#ffb24d"
  glowColor="#a855f7"
  planetColor="#4b3a8c"
  backgroundColor="#05060a"
/>
```

The import path matches the file path above; change it if you move the component. Every value shown is the documented default — pass only what you actually want to change. The snippet lists the tunable props only: if the component's props type in the source requires others (content, handlers, data), pass those too.

## Integration rules

- Keep the `"use client"` directive. This is a client component and will not render as a Server Component.
- It fills its parent. Give the wrapper an explicit height (or a definite grid area) — against a height-auto parent it collapses to nothing.
- It runs a free-running animation loop. Halt it when off-screen or backgrounded if you care about battery.
- The `touch-action: none` on the hit target is load-bearing — without it a finger drag scrolls the page instead of driving the effect. Do not strip it as a stray utility class.
- The peer hook is required, not optional. Copy it to `hooks/use-animation-loop.ts` so the component's `@/hooks/use-animation-loop` import resolves.
- It owns a GPU/canvas context and releases it on unmount. Preserve the cleanup return — leaking contexts kills the tab after a few navigations.

## Your task

1. Tell me where in my project this should live and why.
2. Create the files above verbatim.
3. Wire the component into the place I point you at, with sensible props for that context.
4. Flag anything in my setup that conflicts with the stack assumptions above.

Do not restyle the component or alter the animation math unless I ask.
