# Integrate `Flipdot` from Motion Garden

You are helping me add the **Flipdot** 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:** Flipdot
- **Category:** Text Animations
- **Summary:** A mechanical flip-dot sign. Each word is drawn on a grid of small discs. To show the next word, the discs turn over in a sweep: by column, on a diagonal, out from the center, or at random. A disc squashes as it turns and swings a little past flat before it settles. Hover to flip the discs under the pointer, or click to send a wave across the sign.
- **Reference:** https://motion-garden.netlify.app/components/flipdot
- **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
# Flipdot needs no npm packages
```

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

```tsx
"use client";

import {
	useEffect,
	useLayoutEffect,
	useRef,
	useSyncExternalStore,
} from "react";
import { useAnimationLoop, type Metrics } from "@/hooks/use-animation-loop";

export type FlipdotCascade = "columns" | "diagonal" | "radial" | "random";

export interface FlipdotProps {
	words?: string[];
	rows?: number;
	cascade?: FlipdotCascade;
	stagger?: number;
	flipDuration?: number;
	overshoot?: number;
	hold?: number;
	ripple?: boolean;
	onColor?: string;
	offColor?: string;
	boardColor?: string;
	fontFamily?: string;
	paused?: boolean;
	reducedMotion?: boolean;
	className?: string;
}

const DEFAULT_WORDS = ["FLIP", "DOT"];

const SYSTEM_FONT = 'ui-sans-serif, system-ui, "Segoe UI", sans-serif';
const WEIGHT = 800;

const DISC = 0.42;
const SOCKET = 0.47;
const SHADES = 12;
const EDGE = 0.06;
const GLINT = 0.3;

const BRUSH = 1.2;
const BRUSH_HOLD = 0.45;
const RIPPLE_SPEED = 26;
const RIPPLE_HOLD = 0.32;
const MAX_RIPPLES = 3;

const FACE_BELOW = 10;

const FACE: Record<string, string> = {
	A: "5ehhvhhh",
	B: "5uhhuhhu",
	C: "5ehggghe",
	D: "5uhhhhhu",
	E: "5vgguggv",
	F: "5vgguggg",
	G: "5ehgnhhf",
	H: "5hhhvhhh",
	I: "37222227",
	J: "572222ic",
	K: "5hikokih",
	L: "5ggggggv",
	M: "5hrllhhh",
	N: "5hhpljhh",
	O: "5ehhhhhe",
	P: "5uhhuggg",
	Q: "5ehhhlid",
	R: "5uhhukih",
	S: "5fgge11u",
	T: "5v444444",
	U: "5hhhhhhe",
	V: "5hhhhha4",
	W: "5hhhllla",
	X: "5hha4ahh",
	Y: "5hha4444",
	Z: "5v1248gv",
	"0": "5ehjlphe",
	"1": "54c4444e",
	"2": "5eh1248v",
	"3": "5v2421he",
	"4": "526aiv22",
	"5": "5vgu11he",
	"6": "568guhhe",
	"7": "5v124888",
	"8": "5ehhehhe",
	"9": "5ehhf12c",
	" ": "20000000",
	".": "10000001",
	",": "20000012",
	"!": "11111101",
	"?": "5eh12404",
	"-": "4000f000",
	":": "10100010",
	"'": "11100000",
	'"': "35500000",
	"/": "511248gg",
	"+": "5044v440",
	"=": "400f0f00",
	"(": "31244421",
	")": "34211124",
	"&": "5cik8lid",
	"#": "5aavavaa",
	"*": "504lel40",
	"%": "5op248j3",
	_: "5000000v",
	"<": "41248421",
	">": "48421248",
};

interface Glyph {
	w: number;
	bits: number[];
}

const GLYPHS = decodeFace(FACE);

type RGB = [number, number, number];

interface Plate {
	bits: Uint8Array;
	x: number;
	base: number;
	size: number;
	gap: number;
}

interface Ink {
	asc: number;
	desc: number;
	left: number;
	right: number;
	width: number;
	fa: number;
	fd: number;
}

interface Ripple {
	x: number;
	y: number;
	t: number;
	reach: number;
	end: number;
}

export default function Flipdot({
	words = DEFAULT_WORDS,
	rows = 14,
	cascade = "diagonal",
	stagger = 20,
	flipDuration = 140,
	overshoot = 0.4,
	hold = 2.2,
	ripple = true,
	onColor = "#e9d5ff",
	offColor = "#1d1824",
	boardColor = "#0c0a10",
	fontFamily,
	paused = false,
	reducedMotion = false,
	className = "",
}: FlipdotProps) {
	const rootRef = useRef<HTMLDivElement>(null);
	const canvasRef = useRef<HTMLCanvasElement>(null);
	const textRef = useRef<HTMLSpanElement>(null);
	const drawRef = useRef<((dt: number) => void | false) | null>(null);
	const resizeRef = useRef<((m: Metrics) => void) | null>(null);

	const systemStill = useSyncExternalStore(
		subscribeMotion,
		readMotion,
		readMotionOnServer,
	);
	const still = reducedMotion || systemStill;
	const font = fontFamily ?? SYSTEM_FONT;
	const custom = fontFamily !== undefined;
	const wordsKey = JSON.stringify(words);

	const latest = {
		words,
		wordsKey,
		rows,
		cascade,
		stagger,
		flipDuration,
		overshoot,
		hold,
		ripple,
		onColor,
		offColor,
		boardColor,
		font,
		custom,
		paused,
		still,
	};
	const live = useRef(latest);
	useLayoutEffect(() => {
		live.current = latest;
	});

	const loop = useAnimationLoop({
		target: rootRef,
		halted: paused || still,
		dpr: "auto",
		onResize: (m) => resizeRef.current?.(m),
		onFrame: ({ dt }) => (drawRef.current ? drawRef.current(dt) : false),
	});

	useEffect(() => {
		const root = rootRef.current;
		const canvas = canvasRef.current;
		const span = textRef.current;
		if (!root || !canvas || !span) return;
		const ctx = canvas.getContext("2d");
		const rest = document.createElement("canvas");
		const rctx = rest.getContext("2d");
		const scratch = document.createElement("canvas");
		const sctx = scratch.getContext("2d", { willReadFrequently: true });
		const probe = document.createElement("canvas");
		probe.width = 1;
		probe.height = 1;
		const pctx = probe.getContext("2d", { willReadFrequently: true });
		if (!ctx || !rctx || !sctx || !pctx) return;

		let bw = 0;
		let bh = 0;
		let dpr = 1;
		let pitch = 0;
		let C = 0;
		let R = 0;
		let N = 0;
		let ox = 0;
		let oy = 0;
		let layoutDirty = true;

		let val = new Uint8Array(0);
		let inv = new Uint8Array(0);
		let to = new Uint8Array(0);
		let from = new Float32Array(0);
		let t0 = new Float64Array(0);
		let dur = new Float32Array(0);
		let backAt = new Float64Array(0);
		let pendAt = new Float64Array(0);
		let pendVal = new Uint8Array(0);
		let shown = new Uint8Array(0);
		let movingList = new Int32Array(0);
		let jitter = new Float32Array(0);
		let spread = new Float32Array(0);
		let order = new Float32Array(0);

		let now = 0;
		let list: string[] = [""];
		let wordIndex = 0;
		let landAt = 0;
		let cascades = 0;
		let started = false;
		let stillApplied = false;
		let contentKey = "";
		let current = "";
		let mode: "face" | "font" = "font";
		let scale = 1;
		const plates = new Map<string, Plate>();
		const inks = new Map<string, Ink>();

		let lookKey = "";
		let boardFill = "#000";
		let glintFill = "#fff";
		let vignette: CanvasGradient | null = null;
		let cellEmpty: HTMLCanvasElement | null = null;
		let cellOff: HTMLCanvasElement | null = null;
		let cellOn: HTMLCanvasElement | null = null;
		let discs: HTMLCanvasElement[][] = [[], []];
		const sprites: HTMLCanvasElement[] = [];
		const sprite = (k: number, p: number): HTMLCanvasElement => {
			let c = sprites[k];
			if (!c) {
				c = document.createElement("canvas");
				sprites[k] = c;
			}
			if (c.width !== p || c.height !== p) {
				c.width = p;
				c.height = p;
			} else {
				c.getContext("2d")?.clearRect(0, 0, p, p);
			}
			return c;
		};

		let fontFor = "";
		let fontOk = false;
		let alive = true;

		const brush = { on: false, x: 0, y: 0 };
		const ripples: Ripple[] = [];

		const allocate = (cols: number, rowCount: number) => {
			C = cols;
			R = rowCount;
			N = C * R;
			val = new Uint8Array(N);
			inv = new Uint8Array(N);
			to = new Uint8Array(N);
			from = new Float32Array(N);
			t0 = new Float64Array(N).fill(-1e9);
			dur = new Float32Array(N).fill(1);
			backAt = new Float64Array(N);
			pendAt = new Float64Array(N).fill(-1);
			pendVal = new Uint8Array(N);
			shown = new Uint8Array(N).fill(255);
			movingList = new Int32Array(N);
			jitter = new Float32Array(N);
			spread = new Float32Array(N);
			order = new Float32Array(N);
			const rand = mulberry32(0x5eed ^ (C * 73856093) ^ (R * 19349663));
			for (let i = 0; i < N; i++) {
				jitter[i] = rand() * 2 - 1;
				spread[i] = 0.9 + rand() * 0.2;
				order[i] = rand();
			}
			plates.clear();
			ripples.length = 0;
		};

		const relayout = (): boolean => {
			layoutDirty = false;
			const L = live.current;
			const rowCount = rowCountOf(L.rows);
			const w = bw / dpr;
			const h = bh / dpr;
			const longest = L.custom ? 0 : faceWidth(L.words);
			const minCols = Math.max(3 * rowCount, longest > 0 ? longest + 2 : 0);
			const css = Math.min((h * 0.86) / rowCount, (w * 0.94) / minCols);
			let p = Math.max(2, Math.round(css * dpr));
			if (p * rowCount > bh) p = Math.max(1, Math.floor(bh / rowCount));
			const cols = Math.max(1, Math.floor((bw * 0.94) / p));
			const changed = cols !== C || rowCount !== R;
			const before = `${pitch}|${ox}|${oy}|${rest.width}x${rest.height}`;
			pitch = p;
			if (changed) allocate(cols, rowCount);
			ox = Math.floor((bw - C * pitch) / 2);
			oy = Math.floor((bh - R * pitch) / 2);
			if (rest.width !== bw) rest.width = bw;
			if (rest.height !== bh) rest.height = bh;
			if (changed || before !== `${pitch}|${ox}|${oy}|${rest.width}x${rest.height}`) lookKey = "";
			return changed;
		};

		const look = () => {
			const L = live.current;
			const key = `${L.onColor}|${L.offColor}|${L.boardColor}|${pitch}|${bw}x${bh}`;
			if (key === lookKey) return;
			lookKey = key;
			const on = readColor(pctx, L.onColor, "#e9d5ff");
			const off = readColor(pctx, L.offColor, "#1d1824");
			const board = readColor(pctx, L.boardColor, "#0c0a10");
			const p = pitch;
			boardFill = rgb(board, 1);
			glintFill = rgb(lift(on, 0.65), 1);

			cellEmpty = sprite(0, p);
			cellOff = sprite(1, p);
			cellOn = sprite(2, p);
			paintSocket(cellEmpty, p, board);
			paintSocket(cellOff, p, board);
			paintDisc(cellOff, p, off, 1);
			paintSocket(cellOn, p, board);
			paintDisc(cellOn, p, on, 1);

			discs = [[], []];
			for (let b = 0; b < SHADES; b++) {
				const shade = 0.55 + (0.45 * b) / (SHADES - 1);
				const dark = sprite(3 + b, p);
				paintDisc(dark, p, off, shade);
				discs[0].push(dark);
				const bright = sprite(3 + SHADES + b, p);
				paintDisc(bright, p, on, shade);
				discs[1].push(bright);
			}

			const g = ctx.createRadialGradient(bw / 2, bh * 0.46, 0, bw / 2, bh * 0.46, Math.hypot(bw, bh) * 0.6);
			g.addColorStop(0, "rgba(255,255,255,0.035)");
			g.addColorStop(0.45, "rgba(0,0,0,0)");
			g.addColorStop(1, "rgba(0,0,0,0.45)");
			vignette = g;

			rctx.setTransform(1, 0, 0, 1, 0, 0);
			rctx.fillStyle = boardFill;
			rctx.fillRect(0, 0, bw, bh);
			rctx.fillStyle = g;
			rctx.fillRect(0, 0, bw, bh);
			shown.fill(255);
		};

		const fontReady = (face: string): boolean => {
			if (face === fontFor) return fontOk;
			fontFor = face;
			const spec = `${WEIGHT} 32px ${face}`;
			let ok = true;
			try {
				ok = !document.fonts || document.fonts.check(spec);
			} catch {
				ok = true;
			}
			fontOk = ok;
			if (!ok) {
				document.fonts
					.load(spec)
					.catch(() => undefined)
					.then(() => {
						if (!alive || fontFor !== face) return;
						fontOk = true;
						inks.clear();
						plates.clear();
						loop.paint();
					});
			}
			return ok;
		};

		const inkOf = (word: string, face: string): Ink => {
			const key = `${face}\n${word}`;
			let m = inks.get(key);
			if (!m) {
				sctx.font = `${WEIGHT} 100px ${face}`;
				const t = sctx.measureText(word);
				m = {
					asc: t.actualBoundingBoxAscent,
					desc: t.actualBoundingBoxDescent,
					left: t.actualBoundingBoxLeft,
					right: t.actualBoundingBoxRight,
					width: t.width,
					fa: t.fontBoundingBoxAscent || 90,
					fd: t.fontBoundingBoxDescent || 22,
				};
				if (inks.size > 256) inks.clear();
				inks.set(key, m);
			}
			return m;
		};

		const fitScale = (m: Ink): number => {
			const h = m.asc + m.desc;
			const w = m.left + m.right;
			if (!(h > 0) || !(w > 0)) return 0;
			let s = (0.74 * 4 * R) / h;
			if (w * s > 0.92 * 4 * C) s = (0.92 * 4 * C) / w;
			return s;
		};

		const pickMode = () => {
			const L = live.current;
			mode = "font";
			scale = 1;
			plates.clear();
			if (L.custom) return;
			let k = Number.POSITIVE_INFINITY;
			for (const word of list) {
				const cols = faceColumns(word);
				if (cols < 0) return;
				if (cols > 0) k = Math.min(k, Math.floor(C / cols));
			}
			k = Math.min(k, Math.floor((R >= 9 ? R - 2 : R) / 7));
			if (!(k >= 1)) return;
			let tallest = Number.POSITIVE_INFINITY;
			for (const word of list) {
				const m = inkOf(word, L.font);
				const s = fitScale(m);
				if (s > 0) tallest = Math.min(tallest, Math.floor(((m.asc + m.desc) * s) / 4));
			}
			if (tallest < FACE_BELOW) {
				mode = "face";
				scale = k;
			}
		};

		const facePlate = (word: string): Plate => {
			const bits = new Uint8Array(N);
			const cols = faceColumns(word);
			const k = scale;
			const left = Math.floor((C - cols * k) / 2);
			const top = Math.floor((R - 7 * k) / 2);
			let x = left;
			for (const ch of word.toUpperCase()) {
				const glyph = GLYPHS.get(ch);
				if (!glyph) continue;
				for (let gy = 0; gy < 7; gy++) {
					const line = glyph.bits[gy];
					for (let gx = 0; gx < glyph.w; gx++) {
						if (((line >> (glyph.w - 1 - gx)) & 1) === 0) continue;
						for (let by = 0; by < k; by++) {
							const r = top + gy * k + by;
							if (r < 0 || r >= R) continue;
							for (let bx = 0; bx < k; bx++) {
								const c = x + gx * k + bx;
								if (c >= 0 && c < C) bits[r * C + c] = 1;
							}
						}
					}
				}
				x += (glyph.w + 1) * k;
			}
			const face = live.current.font;
			const m = inkOf(word, face);
			const cap = Math.max(1, inkOf("H", face).asc);
			const size = (7 * k * 100) / cap;
			const n = Array.from(word).length;
			const natural = (m.width * size) / 100;
			return {
				bits,
				x: left,
				base: top + 7 * k,
				size,
				gap: n > 0 ? (Math.max(0, cols) * k - natural) / n : 0,
			};
		};

		const fontPlate = (word: string): Plate => {
			const bits = new Uint8Array(N);
			const face = live.current.font;
			const m = inkOf(word, face);
			let s = fitScale(m);
			if (s <= 0) return { bits, x: C / 2, base: R / 2, size: R / 2, gap: 0 };
			const h = m.asc + m.desc;
			const tall = Math.max(1, Math.floor((h * s) / 4));
			s = (4 * tall) / h;
			const gw = 4 * C;
			const gh = 4 * R;
			scratch.width = gw;
			scratch.height = gh;
			sctx.font = `${WEIGHT} ${100 * s}px ${face}`;
			sctx.fillStyle = "#fff";
			const top = Math.round((R - tall) / 2);
			const yb = top * 4 + m.asc * s;
			const col = Math.round((C - ((m.left + m.right) * s) / 4) / 2);
			const xo = col * 4 + m.left * s;
			sctx.fillText(word, xo, yb);
			const data = sctx.getImageData(0, 0, gw, gh).data;
			const need = 0.45 * 16 * 255;
			for (let r = 0; r < R; r++) {
				for (let c = 0; c < C; c++) {
					let sum = 0;
					for (let yy = 0; yy < 4; yy++) {
						let o = ((r * 4 + yy) * gw + c * 4) * 4 + 3;
						for (let xx = 0; xx < 4; xx++, o += 4) sum += data[o];
					}
					if (sum > need) bits[r * C + c] = 1;
				}
			}
			return { bits, x: xo / 4, base: yb / 4, size: 25 * s, gap: 0 };
		};

		const plateFor = (word: string): Plate => {
			const key = `${mode}|${scale}|${word}`;
			let plate = plates.get(key);
			if (!plate) {
				plate = mode === "face" ? facePlate(word) : fontPlate(word);
				if (plates.size > 64) plates.clear();
				plates.set(key, plate);
			}
			return plate;
		};

		const placeText = () => {
			const plate = plateFor(current);
			const px = pitch / dpr;
			const size = plate.size * px;
			const m = inkOf(current, live.current.font);
			const fa = (m.fa * size) / 100;
			const fd = (m.fd * size) / 100;
			const left = ox / dpr + plate.x * px;
			const base = oy / dpr + plate.base * px;
			const top = base - ((size - (fa + fd)) / 2 + fa);
			if (span.textContent !== current) span.textContent = current;
			span.style.fontSize = `${size}px`;
			span.style.letterSpacing = `${plate.gap * px}px`;
			span.style.transform = `translate(${left}px, ${top}px)`;
		};

		const valueAt = (i: number, t: number): number => {
			const u = (t - t0[i]) / dur[i];
			if (u >= 1) return to[i];
			if (u <= 0) return from[i];
			return from[i] + (to[i] - from[i]) * backOut(u, 1.7 * live.current.overshoot);
		};

		const retarget = (i: number, at: number) => {
			const target = val[i] ^ inv[i];
			if (target === to[i]) return;
			const t = at < t0[i] ? t0[i] : at;
			from[i] = valueAt(i, t);
			to[i] = target;
			t0[i] = t;
			dur[i] = Math.max(0.016, (Math.max(0, live.current.flipDuration) / 1000) * spread[i]);
		};

		const disturb = (i: number, t: number, length: number) => {
			if (inv[i] === 0) {
				inv[i] = 1;
				retarget(i, t);
				backAt[i] = t + length;
			} else if (t + length > backAt[i]) {
				backAt[i] = t + length;
			}
		};

		const brushAt = (x: number, y: number, t: number) => {
			const c0 = Math.max(0, Math.ceil(x - BRUSH));
			const c1 = Math.min(C - 1, Math.floor(x + BRUSH));
			const r0 = Math.max(0, Math.ceil(y - BRUSH));
			const r1 = Math.min(R - 1, Math.floor(y + BRUSH));
			for (let r = r0; r <= r1; r++) {
				for (let c = c0; c <= c1; c++) {
					const dx = c - x;
					const dy = r - y;
					if (dx * dx + dy * dy <= BRUSH * BRUSH) disturb(r * C + c, t, BRUSH_HOLD);
				}
			}
		};

		const setWord = (word: string) => {
			const plate = plateFor(word);
			for (let i = 0; i < N; i++) {
				const b = plate.bits[i];
				val[i] = b;
				inv[i] = 0;
				to[i] = b;
				from[i] = b;
				t0[i] = -1e9;
				dur[i] = 1;
				pendAt[i] = -1;
				backAt[i] = 0;
			}
			ripples.length = 0;
			landAt = now;
			current = word;
			placeText();
		};

		const cascadeTo = (word: string) => {
			const L = live.current;
			const plate = plateFor(word);
			const s = Math.max(0, L.stagger) / 1000;
			cascades++;
			const phase = (cascades * 0.6180339887) % 1;
			const cx = (C - 1) / 2;
			const cy = (R - 1) / 2;
			let last = 0;
			for (let r = 0; r < R; r++) {
				for (let c = 0; c < C; c++) {
					const i = r * C + c;
					const target = plate.bits[i];
					if (target === val[i]) {
						pendAt[i] = -1;
						continue;
					}
					let step: number;
					if (L.cascade === "columns") step = c;
					else if (L.cascade === "radial") step = 1.4 * Math.hypot(c - cx, r - cy);
					else if (L.cascade === "random") step = ((order[i] + phase) % 1) * C * 0.7;
					else step = c + 0.6 * r;
					const delay = Math.max(0, (step + jitter[i] * 0.15) * s);
					pendAt[i] = now + delay;
					pendVal[i] = target;
					if (delay > last) last = delay;
				}
			}
			landAt = now + last + (Math.max(0, L.flipDuration) / 1000) * 1.1;
			current = word;
			placeText();
		};

		const step = (): boolean => {
			const L = live.current;
			let busy = false;
			for (let i = 0; i < N; i++) {
				if (pendAt[i] < 0) continue;
				if (pendAt[i] <= now) {
					const t = pendAt[i];
					pendAt[i] = -1;
					val[i] = pendVal[i];
					retarget(i, t);
				} else {
					busy = true;
				}
			}
			if (L.ripple && brush.on) brushAt(brush.x, brush.y, now);
			for (let k = ripples.length - 1; k >= 0; k--) {
				const rp = ripples[k];
				const reach = (now - rp.t) * RIPPLE_SPEED;
				if (reach > rp.reach) {
					const c0 = Math.max(0, Math.floor(rp.x - reach));
					const c1 = Math.min(C - 1, Math.ceil(rp.x + reach));
					const r0 = Math.max(0, Math.floor(rp.y - reach));
					const r1 = Math.min(R - 1, Math.ceil(rp.y + reach));
					for (let r = r0; r <= r1; r++) {
						for (let c = c0; c <= c1; c++) {
							const d = Math.hypot(c - rp.x, r - rp.y);
							if (d > rp.reach && d <= reach) {
								disturb(r * C + c, rp.t + d / RIPPLE_SPEED, RIPPLE_HOLD);
							}
						}
					}
					rp.reach = reach;
				}
				if (reach > rp.end) ripples.splice(k, 1);
			}
			for (let i = 0; i < N; i++) {
				if (inv[i] === 0) continue;
				if (backAt[i] <= now) {
					inv[i] = 0;
					retarget(i, backAt[i]);
				} else {
					busy = true;
				}
			}
			return busy || ripples.length > 0;
		};

		const stamp = (i: number, want: number) => {
			const cell = want === 2 ? cellOn : want === 1 ? cellOff : cellEmpty;
			if (!cell) return;
			const c = i % C;
			const r = (i - c) / C;
			const x = ox + c * pitch;
			const y = oy + r * pitch;
			rctx.drawImage(cell, x, y);
			if (want !== 0 && vignette) {
				rctx.fillStyle = vignette;
				rctx.fillRect(x, y, pitch, pitch);
			}
		};

		const render = (): number => {
			let moving = 0;
			for (let i = 0; i < N; i++) {
				const inFlight = now < t0[i] + dur[i];
				const want = inFlight ? 0 : to[i] === 1 ? 2 : 1;
				if (shown[i] !== want) {
					stamp(i, want);
					shown[i] = want;
				}
				if (inFlight) movingList[moving++] = i;
			}

			ctx.setTransform(1, 0, 0, 1, 0, 0);
			ctx.globalAlpha = 1;
			ctx.drawImage(rest, 0, 0);

			const k = 1.7 * live.current.overshoot;
			const glintH = Math.max(1, Math.round(pitch * 0.06));
			const glintW = pitch * DISC * 1.9;
			ctx.fillStyle = glintFill;
			for (let j = 0; j < moving; j++) {
				const i = movingList[j];
				const u = (now - t0[i]) / dur[i];
				const e = u <= 0 ? 0 : backOut(u, k);
				const v = from[i] + (to[i] - from[i]) * e;
				const cs = Math.cos(v * Math.PI);
				const a = Math.abs(cs);
				const sprite = discs[cs < 0 ? 1 : 0][Math.round(a * (SHADES - 1))];
				if (!sprite) continue;
				const c = i % C;
				const r = (i - c) / C;
				const x = ox + c * pitch;
				const cy = oy + r * pitch + pitch / 2;
				const h = pitch * Math.max(a, EDGE);
				ctx.drawImage(sprite, x, cy - h / 2, pitch, h);
				if (a < GLINT) {
					ctx.globalAlpha = (1 - a / GLINT) * 0.75;
					ctx.fillRect(x + (pitch - glintW) / 2, cy - glintH / 2, glintW, glintH);
					ctx.globalAlpha = 1;
				}
			}

			if (vignette && moving > 0) {
				ctx.fillStyle = vignette;
				for (let j = 0; j < moving; j++) {
					const i = movingList[j];
					const c = i % C;
					const r = (i - c) / C;
					ctx.fillRect(ox + c * pitch, oy + r * pitch, pitch, pitch);
				}
			}
			return moving;
		};

		drawRef.current = (dt) => {
			if (bw < 1 || bh < 1) return false;
			const L = live.current;
			const key = `${L.wordsKey}\n${L.font}\n${L.custom ? 1 : 0}`;
			const fresh = !started || key !== contentKey;
			if (fresh) layoutDirty = true;
			let regrid = false;
			if (layoutDirty || rowCountOf(L.rows) !== R) {
				regrid = relayout();
				if (started && !regrid && !fresh) placeText();
			}
			if (N === 0) return false;
			look();

			if (!fontReady(L.font)) {
				render();
				return false;
			}

			if (fresh) {
				started = true;
				contentKey = key;
				list = L.words.length > 0 ? L.words.map((w) => String(w)) : [""];
				pickMode();
				wordIndex = 0;
				if (L.still || L.paused) setWord(list[0]);
				else cascadeTo(list[0]);
			} else if (regrid) {
				pickMode();
				setWord(list[wordIndex] ?? list[0]);
			}

			let busy = false;
			if (L.still) {
				if (!stillApplied) {
					stillApplied = true;
					brush.on = false;
					setWord(list[wordIndex] ?? list[0]);
				}
			} else {
				stillApplied = false;
				now += dt;
				if (list.length > 1 && now >= landAt + Math.max(0, L.hold)) {
					wordIndex = (wordIndex + 1) % list.length;
					cascadeTo(list[wordIndex]);
				}
				busy = step();
			}

			const moving = render();

			if (list.length < 2 && moving === 0 && !busy && !brush.on) return false;
		};

		resizeRef.current = (m) => {
			if (canvas.width !== m.bufferWidth) canvas.width = m.bufferWidth;
			if (canvas.height !== m.bufferHeight) canvas.height = m.bufferHeight;
			ctx.setTransform(1, 0, 0, 1, 0, 0);
			bw = m.bufferWidth;
			bh = m.bufferHeight;
			dpr = m.width > 0 ? m.bufferWidth / m.width : m.dpr;
			layoutDirty = true;
		};

		const toDots = (e: PointerEvent): [number, number] | null => {
			const rect = root.getBoundingClientRect();
			if (rect.width <= 0 || rect.height <= 0 || pitch <= 0) return null;
			const x = (e.clientX - rect.left) * (bw / rect.width);
			const y = (e.clientY - rect.top) * (bh / rect.height);
			return [(x - ox) / pitch - 0.5, (y - oy) / pitch - 0.5];
		};

		const interactive = () => {
			const L = live.current;
			return started && N > 0 && L.ripple && !L.paused && !L.still;
		};

		const onMove = (e: PointerEvent) => {
			if (e.pointerType !== "mouse") return;
			if (!interactive()) {
				brush.on = false;
				return;
			}
			const pt = toDots(e);
			if (!pt) return;
			if (brush.on) {
				const dx = pt[0] - brush.x;
				const dy = pt[1] - brush.y;
				const steps = Math.min(400, Math.ceil(Math.hypot(dx, dy) / 0.5));
				for (let s = 1; s <= steps; s++) {
					brushAt(brush.x + (dx * s) / steps, brush.y + (dy * s) / steps, now);
				}
			} else {
				brushAt(pt[0], pt[1], now);
			}
			brush.on = true;
			brush.x = pt[0];
			brush.y = pt[1];
			loop.start();
		};

		const onLeave = () => {
			brush.on = false;
		};

		const onDown = (e: PointerEvent) => {
			if (!interactive()) return;
			if (e.pointerType === "mouse" && e.button !== 0) return;
			const pt = toDots(e);
			if (!pt) return;
			if (ripples.length >= MAX_RIPPLES) ripples.shift();
			const far = Math.max(
				Math.hypot(pt[0], pt[1]),
				Math.hypot(C - 1 - pt[0], pt[1]),
				Math.hypot(pt[0], R - 1 - pt[1]),
				Math.hypot(C - 1 - pt[0], R - 1 - pt[1]),
			);
			ripples.push({ x: pt[0], y: pt[1], t: now, reach: -1, end: far + 1 });
			loop.start();
		};

		root.addEventListener("pointermove", onMove);
		root.addEventListener("pointerleave", onLeave);
		root.addEventListener("pointercancel", onLeave);
		root.addEventListener("pointerdown", onDown);

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

		return () => {
			alive = false;
			drawRef.current = null;
			resizeRef.current = null;
			root.removeEventListener("pointermove", onMove);
			root.removeEventListener("pointerleave", onLeave);
			root.removeEventListener("pointercancel", onLeave);
			root.removeEventListener("pointerdown", onDown);
			for (const c of [rest, scratch, probe, ...sprites]) {
				c.width = 0;
				c.height = 0;
			}
		};
	}, [loop]);

	useEffect(() => {
		loop.paint();
	}, [
		loop,
		wordsKey,
		rows,
		cascade,
		stagger,
		flipDuration,
		overshoot,
		hold,
		ripple,
		onColor,
		offColor,
		boardColor,
		font,
		paused,
		still,
	]);

	return (
		<div
			ref={rootRef}
			className={`relative h-full w-full overflow-hidden ${className}`.trim()}
		>
			<canvas
				ref={canvasRef}
				aria-hidden="true"
				className="absolute inset-0 block size-full"
			/>
			<span
				ref={textRef}
				className="absolute top-0 left-0 leading-none font-extrabold whitespace-nowrap text-transparent select-text"
				style={{ fontFamily: font }}
			>
				{words[0] ?? ""}
			</span>
		</div>
	);
}

function faceColumns(word: string): number {
	let cols = 0;
	let n = 0;
	for (const ch of word.toUpperCase()) {
		const glyph = GLYPHS.get(ch);
		if (!glyph) return -1;
		cols += glyph.w + (n > 0 ? 1 : 0);
		n++;
	}
	return cols;
}

function faceWidth(list: string[]): number {
	let most = 0;
	for (const word of list) {
		const cols = faceColumns(String(word));
		if (cols < 0) return 0;
		if (cols > most) most = cols;
	}
	return most;
}

function rowCountOf(value: number): number {
	return Number.isFinite(value) ? Math.max(1, Math.min(64, Math.round(value))) : 14;
}

function subscribeMotion(onChange: () => void): () => void {
	if (typeof window === "undefined" || !window.matchMedia) return () => {};
	const query = window.matchMedia("(prefers-reduced-motion: reduce)");
	query.addEventListener("change", onChange);
	return () => query.removeEventListener("change", onChange);
}

function readMotion(): boolean {
	return (
		typeof window !== "undefined" &&
		!!window.matchMedia &&
		window.matchMedia("(prefers-reduced-motion: reduce)").matches
	);
}

function readMotionOnServer(): boolean {
	return false;
}

function decodeFace(face: Record<string, string>): Map<string, Glyph> {
	const out = new Map<string, Glyph>();
	for (const ch of Object.keys(face)) {
		const code = face[ch];
		out.set(ch, {
			w: parseInt(code.charAt(0), 10),
			bits: Array.from(code.slice(1), (digit) => parseInt(digit, 32)),
		});
	}
	return out;
}

function backOut(t: number, s: number): number {
	const u = t - 1;
	return 1 + (s + 1) * u * u * u + s * u * u;
}

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

function readColor(probe: CanvasRenderingContext2D, value: string, fallback: string): RGB {
	probe.fillStyle = fallback;
	probe.fillStyle = value;
	probe.clearRect(0, 0, 1, 1);
	probe.fillRect(0, 0, 1, 1);
	const d = probe.getImageData(0, 0, 1, 1).data;
	return [d[0], d[1], d[2]];
}

function rgb(c: RGB, k: number): string {
	return `rgb(${Math.round(c[0] * k)},${Math.round(c[1] * k)},${Math.round(c[2] * k)})`;
}

function lift(c: RGB, k: number): RGB {
	return [c[0] + (255 - c[0]) * k, c[1] + (255 - c[1]) * k, c[2] + (255 - c[2]) * k];
}

function sink(c: RGB, k: number): RGB {
	return [c[0] * (1 - k), c[1] * (1 - k), c[2] * (1 - k)];
}

function paintSocket(cell: HTMLCanvasElement, p: number, board: RGB) {
	const g = cell.getContext("2d");
	if (!g) return;
	const c = p / 2;
	const r = SOCKET * p;
	g.fillStyle = rgb(board, 1);
	g.fillRect(0, 0, p, p);
	const hole = g.createLinearGradient(0, c - r, 0, c + r);
	hole.addColorStop(0, rgb(board, 0.2));
	hole.addColorStop(1, rgb(board, 0.55));
	g.fillStyle = hole;
	g.beginPath();
	g.arc(c, c, r, 0, Math.PI * 2);
	g.fill();
	if (p >= 8) {
		const lw = Math.max(1, p * 0.035);
		g.strokeStyle = rgb(lift(board, 0.16), 1);
		g.globalAlpha = 0.6;
		g.lineWidth = lw;
		g.beginPath();
		g.arc(c, c, r - lw / 2, Math.PI * 0.18, Math.PI * 0.82);
		g.stroke();
		g.globalAlpha = 1;
	}
}

function paintDisc(cell: HTMLCanvasElement, p: number, face: RGB, shade: number) {
	const g = cell.getContext("2d");
	if (!g) return;
	const c = p / 2;
	const r = DISC * p;
	const fill = g.createLinearGradient(0, c - r, 0, c + r);
	fill.addColorStop(0, rgb(lift(face, 0.14), shade));
	fill.addColorStop(1, rgb(sink(face, 0.18), shade));
	g.fillStyle = fill;
	g.beginPath();
	g.arc(c, c, r, 0, Math.PI * 2);
	g.fill();
	if (p >= 6) {
		const lw = Math.max(0.75, p * 0.03);
		g.strokeStyle = rgb(sink(face, 0.45), shade);
		g.globalAlpha = 0.55;
		g.lineWidth = lw;
		g.beginPath();
		g.arc(c, c, r - lw / 2, 0, Math.PI * 2);
		g.stroke();
		g.globalAlpha = 1;
	}
}
```

### 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 |
| --- | --- | --- | --- |
| `rows` | `number` | `14` | Rows of dots on the sign. The columns fill the width. Range 7–28. |
| `cascade` | `"columns" | "diagonal" | "radial" | "random"` | `"diagonal"` | The order the discs turn in when the word changes. |
| `stagger` | `number` | `20` | Delay between one step of the cascade and the next. Range 0–120 ms. |
| `flipDuration` | `number` | `140` | Time one disc takes to turn over. Range 40–600 ms. |
| `overshoot` | `number` | `0.4` | How far a disc swings past flat before it settles. Range 0–1.5. |
| `hold` | `number` | `2.2` | How long each word stays up after it lands. Range 0.6–8 s. |
| `ripple` | `boolean` | `true` | The pointer flips the discs it passes over, and a click sends a wave across the sign. |
| `onColor` | `string (hex)` | `"#e9d5ff"` | The bright face of a disc. |
| `offColor` | `string (hex)` | `"#1d1824"` | The dark face of a disc. |
| `boardColor` | `string (hex)` | `"#0c0a10"` | The sign behind the discs. |

## Usage

```tsx
import Flipdot from "@/components/registry/flipdot/flipdot";

<Flipdot
  rows={14}
  cascade="diagonal"
  stagger={20}
  flipDuration={140}
  overshoot={0.4}
  hold={2.2}
  ripple={true}
  onColor="#e9d5ff"
  offColor="#1d1824"
  boardColor="#0c0a10"
/>
```

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 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.
