# Integrate `Penumbra` from Motion Garden

You are helping me add the **Penumbra** 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:** Penumbra
- **Category:** Hero Templates
- **Summary:** A cloud of dark shards hangs between a spotlight and a wall, beside left-aligned copy. From most angles its shadow looks like noise. Turn the cloud to its true angle and the shadow spells a word. Let go and it turns back.
- **Reference:** https://motion-garden.netlify.app/components/penumbra
- **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 three
```

## 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/penumbra/penumbra.tsx`

```tsx
"use client";

import { memo, useEffect, useRef, useState } from "react";
import * as THREE from "three";
import { useAnimationLoop, type Metrics } from "@/hooks/use-animation-loop";

export interface PenumbraProps {
	title?: string;
	subtitle?: string;
	ctaLabel?: string;
	onCtaClick?: () => void;
	word?: string;
	shardCount?: "400" | "800" | "1600";
	lightColor?: string;
	rimColor?: string;
	shardColor?: string;
	wallColor?: string;
	shardSize?: number;
	scatter?: number;
	softness?: number;
	lightIntensity?: number;
	haze?: number;
	drift?: number;
	snapBack?: boolean;
	parallax?: boolean;
	paused?: boolean;
	reducedMotion?: boolean;
	className?: string;
}

export type PenumbraShardCount = NonNullable<PenumbraProps["shardCount"]>;

const COUNTS: Record<PenumbraShardCount, number> = {
	"400": 400,
	"800": 800,
	"1600": 1600,
};

const TAU = Math.PI * 2;

const LIGHT = new THREE.Vector3(3.4, 3.1, 8.2);
const WORD_CENTER = new THREE.Vector3(0, 0.25, 0);
const WORD_H = 1.35;
const WORD_MAX_W = 5.8;

const T0 = 0.56;
const T_SPAN = 0.26;
const DRIFT_T = 0.055;
const T_MIN = 0.1;
const T_MAX = 0.9;
const CLOUD_CENTER = LIGHT.clone().lerp(WORD_CENTER, T0);

const SHARD_COVER = 1.04;

const MASK_MARGIN = 1.38;
const POOL_ASPECT = 2.3;
const MASK_W = 1024;

const CAM_DIST = 13.2;
const CAM_YAW = -0.36;
const CAM_PITCH = 0.04;
const CAM_TARGET = new THREE.Vector3(1.05, 1.0, 2.2);

const PITCH_LIMIT = 1.25;
const SPRING_K = 15;
const SPRING_DAMP = 0.6;
const DETENT = 0.11;

const PERIOD = 600;
const DUST_COUNT = 280;
const BEAM_SEGMENTS = 96;

const FONT = '900 200px "Arial Black", "Helvetica Neue", Helvetica, Arial, system-ui, sans-serif';

function mulberry32(seed: number) {
	let a = seed >>> 0;
	return () => {
		a = (a + 0x6d2b79f5) >>> 0;
		let t = a;
		t = Math.imul(t ^ (t >>> 15), t | 1);
		t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
	};
}

function hashWord(word: string) {
	let h = 0x811c9dc5;
	for (let i = 0; i < word.length; i++) {
		h ^= word.charCodeAt(i);
		h = Math.imul(h, 0x01000193);
	}
	return h >>> 0;
}

interface Cloud {
	count: number;
	target: Float32Array;
	depth: Float32Array;
	motion: Float32Array;
	orient: Float32Array;
	stretch: Float32Array;
	cell: number;
	halfW: number;
	halfH: number;
}

function buildCloud(word: string, count: number): Cloud {
	const rand = mulberry32(0x9e3779b9 ^ hashWord(word) ^ count);
	const text = word.trim() || " ";
	const canvas = document.createElement("canvas");
	const ctx = canvas.getContext("2d", { willReadFrequently: true });
	let halfW = 1;
	let halfH = WORD_H / 2;
	const points: number[] = [];
	let cell = 0.1;
	if (ctx) {
		ctx.font = FONT;
		const w = Math.ceil(ctx.measureText(text).width) + 80;
		canvas.width = Math.max(64, w);
		canvas.height = 300;
		ctx.font = FONT;
		ctx.fillStyle = "#fff";
		ctx.textBaseline = "middle";
		ctx.textAlign = "center";
		ctx.fillText(text, canvas.width / 2, canvas.height / 2);
		const data = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
		const W = canvas.width;
		const H = canvas.height;
		const ink = (x: number, y: number) => {
			const xi = Math.min(W - 1, Math.max(0, Math.floor(x)));
			const yi = Math.min(H - 1, Math.max(0, Math.floor(y)));
			return data[(yi * W + xi) * 4 + 3] > 127;
		};
		let x0 = W;
		let x1 = 0;
		let y0 = H;
		let y1 = 0;
		let area = 0;
		for (let y = 0; y < H; y++) {
			for (let x = 0; x < W; x++) {
				if (data[(y * W + x) * 4 + 3] > 127) {
					area++;
					if (x < x0) x0 = x;
					if (x > x1) x1 = x;
					if (y < y0) y0 = y;
					if (y > y1) y1 = y;
				}
			}
		}
		if (area > 0) {
			const pxW = x1 - x0 + 1;
			const pxH = y1 - y0 + 1;
			const scale = Math.min(WORD_H / pxH, WORD_MAX_W / pxW);
			halfW = (pxW * scale) / 2;
			halfH = (pxH * scale) / 2;
			const cx = (x0 + x1 + 1) / 2;
			const cy = (y0 + y1 + 1) / 2;
			const spacing = Math.sqrt(area / count);
			const picked: Array<[number, number]> = [];
			for (let gy = y0; gy <= y1; gy += spacing) {
				for (let gx = x0; gx <= x1; gx += spacing) {
					const sx = gx + (0.5 + (rand() - 0.5) * 0.8) * spacing;
					const sy = gy + (0.5 + (rand() - 0.5) * 0.8) * spacing;
					if (ink(sx, sy)) picked.push([sx, sy]);
				}
			}
			for (let i = picked.length - 1; i > 0; i--) {
				const j = Math.floor(rand() * (i + 1));
				const swap = picked[i];
				picked[i] = picked[j];
				picked[j] = swap;
			}
			picked.length = Math.min(picked.length, count);
			let guard = 0;
			while (picked.length < count && guard++ < count * 400) {
				const sx = x0 + rand() * pxW;
				const sy = y0 + rand() * pxH;
				if (ink(sx, sy)) picked.push([sx, sy]);
			}
			for (const [sx, sy] of picked) {
				points.push(
					WORD_CENTER.x + (sx - cx) * scale,
					WORD_CENTER.y - (sy - cy) * scale,
				);
			}
			cell = spacing * scale;
		}
	}
	while (points.length < count * 2) {
		points.push(
			WORD_CENTER.x + (rand() - 0.5) * 2 * halfW,
			WORD_CENTER.y + (rand() - 0.5) * 2 * halfH,
		);
	}

	const target = new Float32Array(points.slice(0, count * 2));
	const depth = new Float32Array(count);
	const motion = new Float32Array(count * 3);
	const orient = new Float32Array(count * 4);
	const stretch = new Float32Array(count * 2);
	const z = new THREE.Vector3(0, 0, 1);
	const dir = new THREE.Vector3();
	const q = new THREE.Quaternion();
	const roll = new THREE.Quaternion();
	for (let i = 0; i < count; i++) {
		depth[i] = rand() + rand() - 1;
		motion[i * 3] = rand() * TAU;
		motion[i * 3 + 1] = 0.25 + rand() * 0.35;
		motion[i * 3 + 2] = rand() * TAU;
		dir.set(target[i * 2] - LIGHT.x, target[i * 2 + 1] - LIGHT.y, -LIGHT.z).normalize();
		q.setFromUnitVectors(z, dir);
		roll.setFromAxisAngle(z, rand() * TAU);
		q.multiply(roll);
		orient[i * 4] = q.x;
		orient[i * 4 + 1] = q.y;
		orient[i * 4 + 2] = q.z;
		orient[i * 4 + 3] = q.w;
		const s = 0.8 + rand() * 0.4;
		stretch[i * 2] = s * (0.8 + rand() * 0.4);
		stretch[i * 2 + 1] = s / Math.sqrt(stretch[i * 2] / s);
	}
	return { count, target, depth, motion, orient, stretch, cell, halfW, halfH };
}

function buildShardGeometry() {
	const tri: Array<[number, number]> = [
		[0, 1.15],
		[-0.9, -0.55],
		[0.75, -0.7],
	];
	const h = 0.07;
	const pos: number[] = [];
	const v = (i: number, z: number) => [tri[i][0], tri[i][1], z];
	pos.push(...v(0, h), ...v(1, h), ...v(2, h));
	pos.push(...v(0, -h), ...v(2, -h), ...v(1, -h));
	for (let i = 0; i < 3; i++) {
		const j = (i + 1) % 3;
		pos.push(...v(i, h), ...v(i, -h), ...v(j, h));
		pos.push(...v(j, h), ...v(i, -h), ...v(j, -h));
	}
	const g = new THREE.BufferGeometry();
	g.setAttribute("position", new THREE.Float32BufferAttribute(pos, 3));
	return g;
}

const POOL_GLSL =  `
float poolMask(vec2 n) {
	vec2 a = abs(n);
	float r = pow(a.x * a.x * a.x + a.y * a.y * a.y, 1.0 / 3.0);
	return (1.0 - smoothstep(0.76, 1.0, r)) * (0.8 + 0.2 * (1.0 - r * r));
}
`;

const SHARD_VERT =  `
varying vec3 vWorld;
void main() {
	vec4 p = vec4(position, 1.0);
	#ifdef USE_INSTANCING
	p = instanceMatrix * p;
	#endif
	vec4 w = modelMatrix * p;
	vWorld = w.xyz;
	gl_Position = projectionMatrix * viewMatrix * w;
}
`;

const SHARD_FRAG =  `
precision highp float;
varying vec3 vWorld;
uniform vec3 uShard;
uniform vec3 uRim;
uniform vec3 uLight;
uniform vec3 uLightPos;
uniform float uIntensity;
uniform mat4 uMaskVP;
${POOL_GLSL}
void main() {
	vec3 n = normalize(cross(dFdx(vWorld), dFdy(vWorld)));
	vec3 v = normalize(cameraPosition - vWorld);
	if (dot(n, v) < 0.0) n = -n;
	vec3 l = normalize(uLightPos - vWorld);
	vec4 c = uMaskVP * vec4(vWorld, 1.0);
	float beam = c.w > 0.0 ? poolMask(c.xy / c.w) : 0.0;
	beam = 0.25 + 0.75 * beam;
	float diff = max(dot(n, l), 0.0);
	vec3 h = normalize(l + v);
	float spec = pow(max(dot(n, h), 0.0), 48.0);
	float fres = pow(1.0 - max(dot(n, v), 0.0), 3.0);
	vec3 rimDir = normalize(vec3(-0.45, 0.55, -0.7));
	float back = pow(max(dot(n, rimDir), 0.0), 2.0);
	vec3 col = uShard * (0.35 + diff * beam * uIntensity * 1.6 * uLight);
	col += uLight * spec * beam * uIntensity * 0.9;
	col += uRim * (fres * 0.22 + back * 0.28);
	gl_FragColor = vec4(col, 1.0);
	#include <tonemapping_fragment>
	#include <colorspace_fragment>
}
`;

const WALL_VERT =  `
varying vec3 vWorld;
void main() {
	vec4 w = modelMatrix * vec4(position, 1.0);
	vWorld = w.xyz;
	gl_Position = projectionMatrix * viewMatrix * w;
}
`;

const WALL_FRAG =  `
precision highp float;
varying vec3 vWorld;
uniform sampler2D uMask;
uniform mat4 uMaskVP;
uniform vec3 uWall;
uniform vec3 uLight;
uniform vec3 uRim;
uniform vec3 uLightPos;
uniform float uIntensity;
uniform float uAlign;
${POOL_GLSL}
float hash(vec2 p) {
	return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453);
}
float vnoise(vec2 p) {
	vec2 i = floor(p);
	vec2 f = fract(p);
	f = f * f * (3.0 - 2.0 * f);
	return mix(mix(hash(i), hash(i + vec2(1.0, 0.0)), f.x), mix(hash(i + vec2(0.0, 1.0)), hash(i + vec2(1.0, 1.0)), f.x), f.y);
}
void main() {
	vec4 c = uMaskVP * vec4(vWorld, 1.0);
	vec2 n = c.xy / max(c.w, 1e-4);
	float front = step(0.0, c.w);
	vec2 uv = n * 0.5 + 0.5;
	float inside = front * step(abs(n.x), 1.0) * step(abs(n.y), 1.0);
	float occ = texture2D(uMask, uv).r * inside;
	float pool = poolMask(n) * front;
	vec3 l = normalize(uLightPos - vWorld);
	float lambert = max(l.z, 0.0);
	float lit = pool * lambert * (1.0 - occ * 0.93);
	float spill = front * exp(-dot(n, n) * 0.55) * 0.07;
	float plaster = 0.9 + 0.07 * vnoise(vWorld.xy * 7.0) + 0.03 * vnoise(vWorld.xy * 31.0);
	vec3 col = uWall * plaster * (0.045 + spill * uLight * uIntensity + uLight * uIntensity * lit * 1.1);
	float fringe = occ * (1.0 - occ) * 4.0;
	col += uRim * fringe * pool * uIntensity * (0.03 + 0.07 * uAlign);
	gl_FragColor = vec4(col, 1.0);
	#include <tonemapping_fragment>
	#include <colorspace_fragment>
}
`;

const PROJECT_GLSL =  `
uniform vec3 uLightPos;
uniform mat3 uLightRot;
uniform vec2 uTan;
vec3 beamPoint(vec2 n, float t) {
	vec3 d = uLightRot * vec3(n.x * uTan.x, n.y * uTan.y, -1.0);
	float s = -uLightPos.z / d.z;
	return uLightPos + d * s * t;
}
`;

const BEAM_VERT =  `
attribute vec3 aBeam;
varying vec3 vWorld;
varying float vT;
${PROJECT_GLSL}
void main() {
	vec3 w = beamPoint(aBeam.xy, aBeam.z);
	vWorld = w;
	vT = aBeam.z;
	gl_Position = projectionMatrix * viewMatrix * vec4(w, 1.0);
}
`;

const BEAM_FRAG =  `
precision highp float;
varying vec3 vWorld;
varying float vT;
uniform vec3 uLight;
uniform float uHaze;
uniform float uIntensity;
uniform float uPhase;
void main() {
	vec3 n = normalize(cross(dFdx(vWorld), dFdy(vWorld)));
	vec3 v = normalize(cameraPosition - vWorld);
	float face = pow(abs(dot(n, v)), 1.6);
	float along = smoothstep(0.0, 0.35, vT) * (1.0 - 0.55 * vT) * (1.0 - 0.6 * smoothstep(0.85, 1.0, vT));
	float shimmer = 0.85 + 0.15 * sin(6.2831853 * uPhase * 3.0 + vWorld.x * 2.1 + vWorld.y * 1.3)
		* sin(6.2831853 * uPhase * 2.0 - vWorld.z * 1.7);
	float a = face * along * shimmer * uHaze * 0.16;
	gl_FragColor = vec4(uLight * uIntensity * a, 1.0);
	#include <tonemapping_fragment>
	#include <colorspace_fragment>
}
`;

const DUST_VERT =  `
attribute vec4 aSeed;
attribute vec4 aRate;
uniform float uPhase;
uniform float uFocal;
varying float vAlpha;
${PROJECT_GLSL}
${POOL_GLSL}
void main() {
	float tau = 6.2831853;
	vec2 n = aSeed.xy + 0.05 * vec2(sin(tau * (aRate.x * uPhase) + aSeed.w * tau), cos(tau * (aRate.y * uPhase) + aSeed.z * tau));
	float t = 0.12 + 0.84 * fract(aSeed.z + aRate.z * uPhase);
	vec3 w = beamPoint(n, t);
	vec4 view = viewMatrix * vec4(w, 1.0);
	float dist = -view.z;
	float tw = 0.5 + 0.5 * sin(tau * aRate.w * uPhase + aSeed.w * tau);
	float ends = smoothstep(0.12, 0.25, t) * (1.0 - smoothstep(0.85, 0.96, t));
	vAlpha = poolMask(n) * ends * (0.3 + 0.7 * tw);
	gl_Position = projectionMatrix * view;
	gl_PointSize = clamp((0.02 + aSeed.w * 0.03) * uFocal / max(dist, 0.1), 1.0, 12.0);
}
`;

const DUST_FRAG =  `
precision highp float;
varying float vAlpha;
uniform vec3 uLight;
uniform float uHaze;
uniform float uIntensity;
void main() {
	vec2 d = gl_PointCoord - 0.5;
	float r2 = dot(d, d) * 4.0;
	float a = exp(-r2 * 5.0) * (1.0 - smoothstep(0.7, 1.0, r2));
	gl_FragColor = vec4(uLight * uIntensity * a * vAlpha * uHaze * 0.9, 1.0);
	#include <tonemapping_fragment>
	#include <colorspace_fragment>
}
`;

const QUAD_VERT =  `
varying vec2 vUv;
void main() {
	vUv = uv;
	gl_Position = vec4(position.xy, 0.0, 1.0);
}
`;

const BLUR_FRAG =  `
precision highp float;
varying vec2 vUv;
uniform sampler2D uTex;
uniform vec2 uStep;
void main() {
	float sum = texture2D(uTex, vUv).r * 0.1585;
	sum += (texture2D(uTex, vUv + uStep * 1.0).r + texture2D(uTex, vUv - uStep * 1.0).r) * 0.1465;
	sum += (texture2D(uTex, vUv + uStep * 2.0).r + texture2D(uTex, vUv - uStep * 2.0).r) * 0.1156;
	sum += (texture2D(uTex, vUv + uStep * 3.0).r + texture2D(uTex, vUv - uStep * 3.0).r) * 0.0778;
	sum += (texture2D(uTex, vUv + uStep * 4.0).r + texture2D(uTex, vUv - uStep * 4.0).r) * 0.0447;
	gl_FragColor = vec4(vec3(sum / 0.9277), 1.0);
}
`;

const hexLuma = (hex: string) => {
	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 0.5;
	return (0.2126 * ((n >> 16) & 255) + 0.7152 * ((n >> 8) & 255) + 0.0722 * (n & 255)) / 255;
};

const wrapAngle = (a: number) => {
	const r = ((a + Math.PI) % TAU + TAU) % TAU;
	return r - Math.PI;
};

const Penumbra = memo(
	({
		title = "Find the angle",
		subtitle = "From most sides it is only noise. Turn it until the shadow says something.",
		ctaLabel = "Step into the light",
		onCtaClick,
		word = "SHADE",
		shardCount = "800",
		lightColor = "#f3eeff",
		rimColor = "#a855f7",
		shardColor = "#17141f",
		wallColor = "#77728a",
		shardSize = 1,
		scatter = 0.6,
		softness = 0.35,
		lightIntensity = 1.2,
		haze = 0.35,
		drift = 0.5,
		snapBack = true,
		parallax = true,
		paused = false,
		reducedMotion = false,
		className,
	}: PenumbraProps) => {
		const containerRef = useRef<HTMLDivElement>(null);
		const drawRef = useRef<((dt: number) => void | false) | null>(null);
		const measureRef = useRef<((m: Metrics) => void) | null>(null);
		const rebuildRef = useRef<((count: PenumbraShardCount, word: string) => void) | null>(null);
		const glRef = useRef<WebGLRenderingContext | WebGL2RenderingContext | null>(null);
		const turn = useRef({
			yaw: reducedMotion ? 0 : 0.95,
			pitch: reducedMotion ? 0 : -0.32,
			vYaw: 0,
			vPitch: 0,
			dragging: false,
			touched: false,
			pointerId: -1,
			lastX: 0,
			lastY: 0,
			lastT: 0,
		});
		const pointer = useRef({ x: 0, y: 0, tx: 0, ty: 0 });
		const [fallback, setFallback] = useState(false);
		const [entered, setEntered] = useState(false);
		const pausedRef = useRef(paused);
		pausedRef.current = paused;

		useEffect(() => setEntered(true), []);

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

		const live = useRef({
			lightColor, rimColor, shardColor, wallColor, shardSize, scatter, softness,
			lightIntensity, haze, drift, snapBack, parallax, reducedMotion,
		});
		live.current = {
			lightColor, rimColor, shardColor, wallColor, shardSize, scatter, softness,
			lightIntensity, haze, drift, snapBack, parallax, reducedMotion,
		};

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

			let renderer: THREE.WebGLRenderer;
			try {
				renderer = new THREE.WebGLRenderer({
					antialias: true,
					alpha: false,
					powerPreference: "high-performance",
				});
			} catch {
				setFallback(true);
				return;
			}
			glRef.current = renderer.getContext();
			renderer.toneMapping = THREE.ACESFilmicToneMapping;
			renderer.toneMappingExposure = 1.05;
			const canvas = renderer.domElement;
			canvas.style.display = "block";
			canvas.style.position = "absolute";
			canvas.style.inset = "0";
			container.prepend(canvas);

			const scene = new THREE.Scene();
			scene.background = new THREE.Color("#050408");
			const camera = new THREE.PerspectiveCamera(34, 1, 0.1, 90);
			let shift = [0, 0];
			let landscape = true;
			let distMul = 1;
			let focal = 600;

			const lightCam = new THREE.PerspectiveCamera(30, 2, 0.5, 40);
			lightCam.layers.set(1);
			const maskVP = new THREE.Matrix4();
			const lightRot = new THREE.Matrix3();
			const tan = new THREE.Vector2(0.3, 0.15);
			const rtOpts = {
				type: THREE.UnsignedByteType,
				format: THREE.RGBAFormat,
				depthBuffer: false,
				minFilter: THREE.LinearFilter,
				magFilter: THREE.LinearFilter,
			};
			const maskRT = new THREE.WebGLRenderTarget(MASK_W, 400, rtOpts);
			const blurA = new THREE.WebGLRenderTarget(MASK_W / 2, 200, rtOpts);
			const blurB = new THREE.WebGLRenderTarget(MASK_W / 2, 200, rtOpts);
			const maskMaterial = new THREE.MeshBasicMaterial({
				color: 0xffffff,
				side: THREE.DoubleSide,
			});

			const fitProjector = (cloud: Cloud) => {
				lightCam.position.copy(LIGHT);
				lightCam.up.set(0, 1, 0);
				lightCam.lookAt(WORD_CENTER);
				lightCam.updateMatrixWorld(true);
				const inv = lightCam.matrixWorldInverse;
				let tx = 0;
				let ty = 0;
				const corner = new THREE.Vector3();
				for (const sx of [-1, 1]) {
					for (const sy of [-1, 1]) {
						corner
							.set(WORD_CENTER.x + sx * cloud.halfW, WORD_CENTER.y + sy * cloud.halfH, 0)
							.applyMatrix4(inv);
						tx = Math.max(tx, Math.abs(corner.x / corner.z));
						ty = Math.max(ty, Math.abs(corner.y / corner.z));
					}
				}
				tx *= MASK_MARGIN;
				ty = Math.max(ty * MASK_MARGIN, tx / POOL_ASPECT);
				tan.set(tx, ty);
				lightCam.fov = (2 * Math.atan(ty) * 180) / Math.PI;
				lightCam.aspect = tx / ty;
				lightCam.updateProjectionMatrix();
				maskVP.multiplyMatrices(lightCam.projectionMatrix, inv);
				lightRot.setFromMatrix4(lightCam.matrixWorld);
				const h = Math.max(64, Math.round(MASK_W / lightCam.aspect));
				maskRT.setSize(MASK_W, h);
				blurA.setSize(MASK_W / 2, Math.round(h / 2));
				blurB.setSize(MASK_W / 2, Math.round(h / 2));
			};

			const wallMaterial = new THREE.ShaderMaterial({
				uniforms: {
					uMask: { value: blurB.texture },
					uMaskVP: { value: maskVP },
					uWall: { value: new THREE.Color(wallColor) },
					uLight: { value: new THREE.Color(lightColor) },
					uRim: { value: new THREE.Color(rimColor) },
					uLightPos: { value: LIGHT },
					uIntensity: { value: lightIntensity },
					uAlign: { value: 0 },
				},
				vertexShader: WALL_VERT,
				fragmentShader: WALL_FRAG,
			});
			const wall = new THREE.Mesh(new THREE.PlaneGeometry(70, 46), wallMaterial);
			scene.add(wall);

			const shardGeometry = buildShardGeometry();
			const shardMaterial = new THREE.ShaderMaterial({
				uniforms: {
					uShard: { value: new THREE.Color(shardColor) },
					uRim: { value: new THREE.Color(rimColor) },
					uLight: { value: new THREE.Color(lightColor) },
					uLightPos: { value: LIGHT },
					uIntensity: { value: lightIntensity },
					uMaskVP: { value: maskVP },
				},
				vertexShader: SHARD_VERT,
				fragmentShader: SHARD_FRAG,
				side: THREE.DoubleSide,
			});
			const cloudGroup = new THREE.Group();
			cloudGroup.position.copy(CLOUD_CENTER);
			cloudGroup.rotation.order = "XYZ";
			scene.add(cloudGroup);
			let cloud: Cloud | null = null;
			let shards: THREE.InstancedMesh | null = null;
			let builtKey = "";

			const rebuild = (count: PenumbraShardCount, nextWord: string) => {
				const key = `${count}|${nextWord}`;
				if (key === builtKey) return;
				builtKey = key;
				if (shards) {
					cloudGroup.remove(shards);
					shards.dispose();
				}
				cloud = buildCloud(nextWord, COUNTS[count]);
				fitProjector(cloud);
				shards = new THREE.InstancedMesh(shardGeometry, shardMaterial, cloud.count);
				shards.instanceMatrix.setUsage(THREE.DynamicDrawUsage);
				shards.frustumCulled = false;
				shards.layers.enable(1);
				cloudGroup.add(shards);
				loop.paint();
			};

			const projectUniforms = {
				uLightPos: { value: LIGHT },
				uLightRot: { value: lightRot },
				uTan: { value: tan },
			};
			const shared = {
				uLight: { value: new THREE.Color(lightColor) },
				uHaze: { value: haze },
				uIntensity: { value: lightIntensity },
				uPhase: { value: 0 },
			};
			const beamAttr: number[] = [];
			const beamIndex: number[] = [];
			for (let i = 0; i <= BEAM_SEGMENTS; i++) {
				const a = (i / BEAM_SEGMENTS) * TAU;
				const c = Math.cos(a);
				const s = Math.sin(a);
				const x = Math.sign(c) * Math.pow(Math.abs(c), 2 / 3) * 0.93;
				const y = Math.sign(s) * Math.pow(Math.abs(s), 2 / 3) * 0.93;
				beamAttr.push(x, y, 0.02, x, y, 1);
				if (i < BEAM_SEGMENTS) {
					const k = i * 2;
					beamIndex.push(k, k + 1, k + 2, k + 2, k + 1, k + 3);
				}
			}
			const beamGeometry = new THREE.BufferGeometry();
			beamGeometry.setAttribute("aBeam", new THREE.Float32BufferAttribute(beamAttr, 3));
			beamGeometry.setAttribute(
				"position",
				new THREE.Float32BufferAttribute(new Array(beamAttr.length).fill(0), 3),
			);
			beamGeometry.setIndex(beamIndex);
			const beamMaterial = new THREE.ShaderMaterial({
				uniforms: { ...projectUniforms, ...shared },
				vertexShader: BEAM_VERT,
				fragmentShader: BEAM_FRAG,
				side: THREE.DoubleSide,
				transparent: true,
				depthWrite: false,
				blending: THREE.AdditiveBlending,
			});
			const beam = new THREE.Mesh(beamGeometry, beamMaterial);
			beam.frustumCulled = false;
			beam.renderOrder = 2;
			scene.add(beam);

			const dustRand = mulberry32(0xd057);
			const seeds = new Float32Array(DUST_COUNT * 4);
			const rates = new Float32Array(DUST_COUNT * 4);
			for (let i = 0; i < DUST_COUNT; i++) {
				const a = dustRand() * TAU;
				const r = Math.sqrt(dustRand()) * 0.9;
				seeds[i * 4] = Math.cos(a) * r;
				seeds[i * 4 + 1] = Math.sin(a) * r;
				seeds[i * 4 + 2] = dustRand();
				seeds[i * 4 + 3] = dustRand();
				rates[i * 4] = 2 + Math.floor(dustRand() * 6);
				rates[i * 4 + 1] = 2 + Math.floor(dustRand() * 6);
				rates[i * 4 + 2] = 1 + Math.floor(dustRand() * 3);
				rates[i * 4 + 3] = 40 + Math.floor(dustRand() * 120);
			}
			const dustGeometry = new THREE.BufferGeometry();
			dustGeometry.setAttribute("aSeed", new THREE.BufferAttribute(seeds, 4));
			dustGeometry.setAttribute("aRate", new THREE.BufferAttribute(rates, 4));
			dustGeometry.setAttribute(
				"position",
				new THREE.BufferAttribute(new Float32Array(DUST_COUNT * 3), 3),
			);
			const dustMaterial = new THREE.ShaderMaterial({
				uniforms: { ...projectUniforms, ...shared, uFocal: { value: focal } },
				vertexShader: DUST_VERT,
				fragmentShader: DUST_FRAG,
				transparent: true,
				depthWrite: false,
				blending: THREE.AdditiveBlending,
			});
			const dust = new THREE.Points(dustGeometry, dustMaterial);
			dust.frustumCulled = false;
			dust.renderOrder = 3;
			scene.add(dust);

			const quadCam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
			const blurMaterial = new THREE.ShaderMaterial({
				uniforms: {
					uTex: { value: maskRT.texture },
					uStep: { value: new THREE.Vector2() },
				},
				vertexShader: QUAD_VERT,
				fragmentShader: BLUR_FRAG,
				depthTest: false,
				depthWrite: false,
			});
			const quadScene = new THREE.Scene();
			const quad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), blurMaterial);
			quad.frustumCulled = false;
			quadScene.add(quad);

			rebuild(shardCount, word);
			rebuildRef.current = rebuild;

			let time = 0;
			let phase = 0;
			const m4 = new THREE.Matrix4();
			const pos = new THREE.Vector3();
			const quat = new THREE.Quaternion();
			const wob = new THREE.Quaternion();
			const scl = new THREE.Vector3();
			const black = new THREE.Color(0x000000);

			const placeShards = (scatterAmt: number, driftAmt: number, sizeAmt: number) => {
				if (!cloud || !shards) return;
				const c = cloud;
				const shadow = c.cell * SHARD_COVER * sizeAmt;
				for (let i = 0; i < c.count; i++) {
					const ph = c.motion[i * 3];
					const rate = c.motion[i * 3 + 1];
					let t = T0 + c.depth[i] * T_SPAN * scatterAmt;
					t += Math.sin(ph + time * rate) * DRIFT_T * driftAmt;
					t = Math.min(T_MAX, Math.max(T_MIN, t));
					const wx = c.target[i * 2];
					const wy = c.target[i * 2 + 1];
					pos.set(
						LIGHT.x + (wx - LIGHT.x) * t - CLOUD_CENTER.x,
						LIGHT.y + (wy - LIGHT.y) * t - CLOUD_CENTER.y,
						LIGHT.z * (1 - t) - CLOUD_CENTER.z,
					);
					quat.set(c.orient[i * 4], c.orient[i * 4 + 1], c.orient[i * 4 + 2], c.orient[i * 4 + 3]);
					const w = Math.sin(c.motion[i * 3 + 2] + time * rate * 0.7) * 0.22 * driftAmt;
					wob.set(0, 0, Math.sin(w / 2), Math.cos(w / 2));
					quat.multiply(wob);
					const size = shadow * t;
					scl.set(size * c.stretch[i * 2], size * c.stretch[i * 2 + 1], size);
					m4.compose(pos, quat, scl);
					shards.setMatrixAt(i, m4);
				}
				shards.instanceMatrix.needsUpdate = true;
			};

			drawRef.current = (dt) => {
				const l = live.current;
				const o = turn.current;
				const p = pointer.current;
				const frozen = pausedRef.current;
				const step = frozen ? 0 : Math.min(dt, 1 / 30);
				const still = frozen || l.reducedMotion;

				if (!still) {
					time += step;
					phase = (phase + step / PERIOD) % 1;
				}

				const near = Math.abs(wrapAngle(o.yaw)) < DETENT && Math.abs(o.pitch) < DETENT;
				const pull = l.snapBack || !o.touched || near;
				if (!o.dragging && step > 0) {
					if (pull) {
						o.yaw = wrapAngle(o.yaw);
						const k = l.reducedMotion ? 60 : near && !l.snapBack ? 9 : SPRING_K;
						const damp = l.reducedMotion ? 1 : SPRING_DAMP;
						const c = 2 * Math.sqrt(k) * damp;
						o.vYaw += (-k * o.yaw - c * o.vYaw) * step;
						o.vPitch += (-k * o.pitch - c * o.vPitch) * step;
					} else {
						const f = Math.exp(-2.6 * step);
						o.vYaw *= f;
						o.vPitch *= f;
					}
					o.yaw += o.vYaw * step;
					o.pitch = Math.max(-PITCH_LIMIT, Math.min(PITCH_LIMIT, o.pitch + o.vPitch * step));
					if (Math.abs(o.pitch) >= PITCH_LIMIT) o.vPitch = 0;
				}
				cloudGroup.rotation.set(o.pitch, o.yaw, 0);

				const ease = frozen ? 0 : Math.min(1, Math.min(dt, 1 / 30) * 4);
				const lean = l.parallax && !l.reducedMotion;
				p.x += ((lean ? p.tx : 0) - p.x) * ease;
				p.y += ((lean ? p.ty : 0) - p.y) * ease;

				const yaw = CAM_YAW + p.x * 0.14;
				const pitch = CAM_PITCH + p.y * 0.07;
				camera.position.set(
					CAM_TARGET.x + Math.sin(yaw) * Math.cos(pitch) * CAM_DIST * distMul,
					CAM_TARGET.y + Math.sin(pitch) * CAM_DIST * distMul,
					CAM_TARGET.z + Math.cos(yaw) * Math.cos(pitch) * CAM_DIST * distMul,
				);
				camera.lookAt(CAM_TARGET);
				camera.updateMatrixWorld();

				placeShards(l.scatter, l.reducedMotion ? 0 : l.drift, l.shardSize);

				const off = Math.hypot(wrapAngle(o.yaw), o.pitch);
				wallMaterial.uniforms.uAlign.value = Math.exp(-(off * off) / 0.0025);
				wallMaterial.uniforms.uWall.value.set(l.wallColor);
				wallMaterial.uniforms.uLight.value.set(l.lightColor);
				wallMaterial.uniforms.uRim.value.set(l.rimColor);
				wallMaterial.uniforms.uIntensity.value = l.lightIntensity;
				shardMaterial.uniforms.uShard.value.set(l.shardColor);
				shardMaterial.uniforms.uRim.value.set(l.rimColor);
				shardMaterial.uniforms.uLight.value.set(l.lightColor);
				shardMaterial.uniforms.uIntensity.value = l.lightIntensity;
				shared.uLight.value.set(l.lightColor);
				shared.uHaze.value = l.haze;
				shared.uIntensity.value = l.lightIntensity;
				shared.uPhase.value = phase;
				dustMaterial.uniforms.uFocal.value = focal;
				beam.visible = dust.visible = l.haze > 0.001;

				const bg = scene.background;
				scene.background = black;
				scene.overrideMaterial = maskMaterial;
				renderer.setRenderTarget(maskRT);
				renderer.render(scene, lightCam);
				scene.overrideMaterial = null;
				scene.background = bg;

				const spread = 0.6 + l.softness * l.softness * 7 + l.softness * 2;
				blurMaterial.uniforms.uTex.value = maskRT.texture;
				blurMaterial.uniforms.uStep.value.set(spread / blurA.width, 0);
				renderer.setRenderTarget(blurA);
				renderer.render(quadScene, quadCam);
				blurMaterial.uniforms.uTex.value = blurA.texture;
				blurMaterial.uniforms.uStep.value.set(0, spread / blurA.height);
				renderer.setRenderTarget(blurB);
				renderer.render(quadScene, quadCam);
				renderer.setRenderTarget(null);

				renderer.render(scene, camera);

				if (l.reducedMotion && !frozen) {
					const busy =
						o.dragging ||
						Math.abs(o.vYaw) + Math.abs(o.vPitch) > 0.002 ||
						(pull && Math.abs(wrapAngle(o.yaw)) + Math.abs(o.pitch) > 0.002) ||
						Math.abs(p.x) + Math.abs(p.y) > 0.002;
					if (!busy) return false;
				}
			};

			measureRef.current = ({ width, height, dpr }: Metrics) => {
				const w = Math.max(1, Math.floor(width));
				const h = Math.max(1, Math.floor(height));
				renderer.setPixelRatio(dpr);
				renderer.setSize(w, h);
				const aspect = w / h;
				landscape = aspect >= 1;
				camera.fov = landscape ? 34 : Math.min(52, 34 + (1 - aspect) * 30);
				camera.aspect = aspect;
				camera.updateProjectionMatrix();
				shift = landscape ? [0.4, 0.04] : [0.32, 0.22];
				distMul = landscape ? 1 : 1 + (1 - aspect) * 0.9;
				camera.projectionMatrix.elements[8] = -shift[0];
				camera.projectionMatrix.elements[9] = -shift[1];
				camera.projectionMatrixInverse.copy(camera.projectionMatrix).invert();
				focal = (h * dpr * 0.5) / Math.tan((camera.fov * Math.PI) / 360);
				drawRef.current?.(0);
			};

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

			return () => {
				drawRef.current = null;
				measureRef.current = null;
				rebuildRef.current = null;
				shards?.dispose();
				shardGeometry.dispose();
				shardMaterial.dispose();
				wall.geometry.dispose();
				wallMaterial.dispose();
				beamGeometry.dispose();
				beamMaterial.dispose();
				dustGeometry.dispose();
				dustMaterial.dispose();
				quad.geometry.dispose();
				blurMaterial.dispose();
				maskMaterial.dispose();
				maskRT.dispose();
				blurA.dispose();
				blurB.dispose();
				renderer.dispose();
				if (container.contains(canvas)) container.removeChild(canvas);
			};
			// eslint-disable-next-line react-hooks/exhaustive-deps
		}, [fallback]);

		useEffect(() => {
			rebuildRef.current?.(shardCount, word);
		}, [shardCount, word]);

		useEffect(() => {
			loop.paint();
		}, [
			lightColor, rimColor, shardColor, wallColor, shardSize, scatter, softness,
			lightIntensity, haze, drift, snapBack, parallax, reducedMotion, loop,
		]);

		const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
			if ((e.target as Element).closest("button, a")) return;
			if (e.pointerType === "mouse" && e.button !== 0) return;
			const o = turn.current;
			o.dragging = true;
			o.touched = 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 r = e.currentTarget.getBoundingClientRect();
			if (r.width === 0 || r.height === 0) return;
			pointer.current.tx = ((e.clientX - r.left) / r.width) * 2 - 1;
			pointer.current.ty = -(((e.clientY - r.top) / r.height) * 2 - 1);

			const o = turn.current;
			if (!o.dragging || e.pointerId !== o.pointerId) {
				if (parallax && !reducedMotion && !paused) loop.start();
				return;
			}
			const dx = e.clientX - o.lastX;
			const dy = e.clientY - o.lastY;
			const dt = (e.timeStamp - o.lastT) / 1000;
			const k = 3.4 / Math.max(240, Math.min(r.width, r.height * 1.6));
			const dYaw = dx * k;
			const dPitch = dy * k;
			o.yaw += dYaw;
			o.pitch = Math.max(-PITCH_LIMIT, Math.min(PITCH_LIMIT, o.pitch + dPitch));
			if (dt > 0.001) {
				const blend = Math.min(1, dt * 18);
				o.vYaw += (dYaw / dt - o.vYaw) * blend;
				o.vPitch += (dPitch / dt - o.vPitch) * blend;
			}
			o.lastX = e.clientX;
			o.lastY = e.clientY;
			o.lastT = e.timeStamp;
			loop.start();
		};

		const endDrag = (e: React.PointerEvent<HTMLDivElement>) => {
			const o = turn.current;
			if (e.pointerId !== o.pointerId) return;
			if (e.currentTarget.hasPointerCapture(e.pointerId)) {
				e.currentTarget.releasePointerCapture(e.pointerId);
			}
			if (e.timeStamp - o.lastT > 80) {
				o.vYaw = 0;
				o.vPitch = 0;
			}
			if (reducedMotion) {
				o.vYaw = 0;
				o.vPitch = 0;
			}
			o.dragging = false;
			o.pointerId = -1;
			if (e.pointerType !== "mouse") {
				pointer.current.tx = 0;
				pointer.current.ty = 0;
			}
			loop.start();
		};

		const onPointerLeave = () => {
			if (turn.current.dragging) return;
			pointer.current.tx = 0;
			pointer.current.ty = 0;
			loop.start();
		};

		const rise = (i: number): React.CSSProperties =>
			reducedMotion
				? {}
				: {
						opacity: entered ? 1 : 0,
						transform: entered ? "none" : "translateY(14px)",
						transition: `opacity 700ms cubic-bezier(0.22,1,0.36,1) ${i * 110}ms, transform 700ms cubic-bezier(0.22,1,0.36,1) ${i * 110}ms`,
					};

		const wash = (0.45 + 0.4 * Math.min(1, Math.max(0, (hexLuma(wallColor) - 0.25) / 0.6))).toFixed(2);

		const overlay = (
			<div
				className="pointer-events-none absolute inset-0 z-10 flex flex-col items-start justify-end bg-[linear-gradient(0deg,rgba(4,3,8,var(--penumbra-wash)),rgba(4,3,8,0)_55%)] px-[max(20px,5.5cqi)] pb-[max(20px,6cqi)] text-left [@container(orientation:landscape)]:justify-center [@container(orientation:landscape)]:bg-[linear-gradient(90deg,rgba(4,3,8,var(--penumbra-wash)),rgba(4,3,8,0)_55%)] [@container(orientation:landscape)]:pb-0"
				style={{ ["--penumbra-wash" as string]: wash }}
			>
				{title ? (
					<h1
						className="max-w-[max(260px,40cqi)] text-[max(28px,5.4cqi)] leading-[1.02] font-semibold tracking-tight text-white"
						style={rise(0)}
					>
						{title}
					</h1>
				) : null}
				{subtitle ? (
					<p
						className="mt-[max(10px,1.4cqi)] max-w-[max(220px,34cqi)] text-[max(12px,1.7cqi)] leading-snug text-white/70"
						style={rise(1)}
					>
						{subtitle}
					</p>
				) : null}
				{ctaLabel ? (
					<div className="mt-[max(18px,2.6cqi)]" style={rise(2)}>
						<button
							type="button"
							onClick={onCtaClick}
							className="pointer-events-auto relative cursor-pointer rounded-full px-[max(24px,3.1cqi)] py-[max(10px,1.2cqi)] text-[max(11px,1.25cqi)] font-medium tracking-[0.2em] text-[#0b0a10] uppercase shadow-[0_0_0_1px_rgba(255,255,255,0.18),0_10px_40px_-12px_var(--penumbra-light)] transition-[box-shadow,transform,filter] duration-300 ease-out hover:shadow-[0_0_0_1px_rgba(255,255,255,0.4),0_0_0_5px_var(--penumbra-rim-soft),0_10px_44px_-10px_var(--penumbra-light)] hover:brightness-105 focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-white/70 active:scale-[0.97] motion-reduce:transition-none"
							style={{
								backgroundColor: lightColor,
								["--penumbra-light" as string]: lightColor,
								["--penumbra-rim-soft" as string]: `color-mix(in srgb, ${rimColor} 45%, transparent)`,
							}}
						>
							{ctaLabel}
						</button>
					</div>
				) : null}
			</div>
		);

		const rootClass = [
			"relative h-full w-full cursor-grab overflow-hidden select-none @container-size active:cursor-grabbing [&_canvas]:touch-none",
			className,
		]
			.filter(Boolean)
			.join(" ");

		if (fallback) {
			return (
				<div
					className={rootClass}
					style={{
						backgroundColor: "#050408",
						backgroundImage: `radial-gradient(ellipse 34% 26% at 66% 50%, color-mix(in srgb, ${wallColor} 80%, ${lightColor}) 0%, color-mix(in srgb, ${wallColor} 55%, transparent) 60%, transparent 100%)`,
					}}
				>
					<span
						aria-hidden
						className="absolute top-1/2 left-[66%] -translate-x-1/2 -translate-y-1/2 text-[9cqi] leading-none font-black tracking-tight blur-[1px]"
						style={{ color: "rgba(6,5,10,0.85)" }}
					>
						{word}
					</span>
					{overlay}
				</div>
			);
		}

		return (
			<div
				ref={containerRef}
				className={rootClass}
				onPointerDown={onPointerDown}
				onPointerMove={onPointerMove}
				onPointerUp={endDrag}
				onPointerCancel={endDrag}
				onPointerLeave={onPointerLeave}
			>
				{overlay}
			</div>
		);
	},
);

Penumbra.displayName = "Penumbra";

export default Penumbra;
```

### 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 |
| --- | --- | --- | --- |
| `shardCount` | `"400" | "800" | "1600"` | `"800"` | How many shards, in fixed steps. More shards draw a sharper word. Each step rebuilds the cloud. |
| `lightColor` | `string (hex)` | `"#f3eeff"` | Spotlight color, and the pool of light it throws on the wall. |
| `rimColor` | `string (hex)` | `"#a855f7"` | Edge light on the shards. |
| `shardColor` | `string (hex)` | `"#17141f"` | Base color of the shards. |
| `wallColor` | `string (hex)` | `"#77728a"` | Color of the back wall. |
| `shardSize` | `number` | `1` | Shard size. Small shards leave gaps in the letters. Range 0.6–1.6. |
| `scatter` | `number` | `0.6` | How far the shards spread along the light. More spread looks more random from the side. Range 0–1. |
| `softness` | `number` | `0.35` | How soft the shadow's edge is. 0 is a hard edge. Range 0–1. |
| `lightIntensity` | `number` | `1.2` | Spotlight strength. Range 0.4–2.5. |
| `haze` | `number` | `0.35` | Dust in the light beam. 0 hides the beam. Range 0–1. |
| `drift` | `number` | `0.5` | How far the shards float while idle. They float along the light, so the word holds. Range 0–1. |
| `snapBack` | `boolean` | `true` | Turn back to the true angle after you let go. |
| `parallax` | `boolean` | `true` | The camera leans toward the pointer, easing back on leave. |

## Usage

```tsx
import Penumbra from "@/components/registry/penumbra/penumbra";

<Penumbra
  shardCount="800"
  lightColor="#f3eeff"
  rimColor="#a855f7"
  shardColor="#17141f"
  wallColor="#77728a"
  shardSize={1}
  scatter={0.6}
  softness={0.35}
  lightIntensity={1.2}
  haze={0.35}
  drift={0.5}
  snapBack={true}
  parallax={true}
/>
```

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 takes a `reducedMotion` prop and quiesces when true. Wire it to a `prefers-reduced-motion` listener rather than hardcoding `false`.
- 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.
