# Integrate `Torchlight` from Motion Garden

You are helping me add the **Torchlight** 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:** Torchlight
- **Category:** Micro-interactions
- **Summary:** Content hidden in darkness; the cursor is a torch that reveals only what it touches.
- **Reference:** https://motion-garden.netlify.app/components/torchlight
- **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 clsx tailwind-merge
```

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

```tsx
"use client";

import { useCallback, useRef, type ReactNode } from "react";
import { cn } from "@/lib/utils";

export interface TorchlightProps {
  children?: ReactNode;
  className?: string;
  radius?: number;
  softness?: number;
  darkness?: number;
  restReveal?: number;
  smoothing?: number;
  flicker?: number;
  torchColor?: string;
  reducedMotion?: boolean;
}

const TORCH_CSS = `
@property --torch-x { syntax: "<length>"; inherits: true; initial-value: -9999px; }
@property --torch-y { syntax: "<length>"; inherits: true; initial-value: -9999px; }
@keyframes sg-torch-flicker {
  0%, 100% { opacity: calc(0.4 - var(--sg-flick, 0) * 0.03); transform: scale(1); }
  18%  { opacity: calc(0.4 - var(--sg-flick, 0) * 0.16); transform: scale(calc(1 - var(--sg-flick, 0) * 0.035)); }
  37%  { opacity: 0.4;                                     transform: scale(calc(1 + var(--sg-flick, 0) * 0.025)); }
  55%  { opacity: calc(0.4 - var(--sg-flick, 0) * 0.07); transform: scale(1); }
  72%  { opacity: calc(0.4 - var(--sg-flick, 0) * 0.2);  transform: scale(calc(1 - var(--sg-flick, 0) * 0.02)); }
  88%  { opacity: calc(0.4 - var(--sg-flick, 0) * 0.05); transform: scale(calc(1 + var(--sg-flick, 0) * 0.015)); }
}
@media (prefers-reduced-motion: reduce) {
  [data-sg-torch-glow] { animation: none !important; }
}
`;

export default function Torchlight({
  children,
  className,
  radius = 140,
  softness = 0.5,
  darkness = 0.92,
  restReveal = 0,
  smoothing = 0.15,
  flicker = 0.15,
  torchColor = "#a855f7",
  reducedMotion = false,
}: TorchlightProps) {
  const rootRef = useRef<HTMLDivElement>(null);

  const moveTo = useCallback((clientX: number, clientY: number) => {
    const el = rootRef.current;
    if (!el) return;
    const rect = el.getBoundingClientRect();
    el.style.setProperty("--torch-x", `${clientX - rect.left}px`);
    el.style.setProperty("--torch-y", `${clientY - rect.top}px`);
  }, []);

  const park = useCallback(() => {
    const el = rootRef.current;
    if (!el) return;
    el.style.setProperty("--torch-x", "-9999px");
    el.style.setProperty("--torch-y", "-9999px");
  }, []);

  const onPointerMove = useCallback(
    (e: React.PointerEvent<HTMLDivElement>) => moveTo(e.clientX, e.clientY),
    [moveTo]
  );
  const onTouchMove = useCallback(
    (e: React.TouchEvent<HTMLDivElement>) => {
      const t = e.touches[0];
      if (t) moveTo(t.clientX, t.clientY);
    },
    [moveTo]
  );

  const soft = Math.min(Math.max(softness, 0), 1);
  const inner = Math.max(radius * (1 - soft), 0);
  const outer = radius * (1 + soft) + 1;
  const overlayOpacity =
    Math.min(Math.max(darkness, 0), 1) * (1 - Math.min(Math.max(restReveal, 0), 1));
  const lagSeconds = (0.03 + Math.min(Math.max(smoothing, 0.02), 1) * 0.57).toFixed(3);
  const flickAmt = Math.min(Math.max(flicker, 0), 1);
  const glowActive = !reducedMotion && flickAmt > 0;

  const revealMask = `radial-gradient(circle at var(--torch-x) var(--torch-y), transparent ${inner}px, #000 ${outer}px)`;

  return (
    <div
      ref={rootRef}
      onPointerMove={onPointerMove}
      onPointerLeave={park}
      onTouchMove={onTouchMove}
      onTouchEnd={park}
      onTouchCancel={park}
      className={cn(
        "relative isolate touch-none select-none overflow-hidden",
        className,
      )}
      style={
        {
          "--torch-x": "-9999px",
          "--torch-y": "-9999px",
          transition: `--torch-x ${lagSeconds}s cubic-bezier(0.22, 1, 0.36, 1), --torch-y ${lagSeconds}s cubic-bezier(0.22, 1, 0.36, 1)`,
        } as React.CSSProperties
      }
    >
      <style>{TORCH_CSS}</style>

      <div className="relative z-0">{children}</div>

      <div
        aria-hidden
        className="pointer-events-none absolute inset-0 z-10"
        style={{
          background: "rgb(5 5 8)",
          opacity: overlayOpacity,
          maskImage: revealMask,
          WebkitMaskImage: revealMask,
        }}
      />

      <div
        aria-hidden
        data-sg-torch-glow
        className="pointer-events-none absolute inset-0 z-20"
        style={
          {
            background: `radial-gradient(circle at var(--torch-x) var(--torch-y), ${torchColor} 0px, transparent ${(radius * 1.15).toFixed(0)}px)`,
            mixBlendMode: "plus-lighter",
            transformOrigin: "var(--torch-x) var(--torch-y)",
            opacity: 0.4,
            "--sg-flick": flickAmt,
            animation: glowActive
              ? "sg-torch-flicker 140ms steps(2, end) infinite"
              : "none",
          } as React.CSSProperties
        }
      />
    </div>
  );
}
```

### 2. `lib/utils.ts` — peer util, required

```tsx
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```


## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `radius` | `number` | `140` | Torch light radius. Range 40–400 px. |
| `softness` | `number` | `0.5` | Falloff softness of the light edge. Range 0–1. |
| `darkness` | `number` | `0.92` | How hidden the surrounding content is. Range 0.5–1. |
| `restReveal` | `number` | `0` | Ambient reveal away from the torch. Range 0–0.3. |
| `smoothing` | `number` | `0.15` | How much the light lags the cursor. Range 0.02–1. |
| `flicker` | `number` | `0.15` | Subtle torch flicker (off under reduced motion). Range 0–1. |
| `torchColor` | `string (hex)` | `"#a855f7"` | Amethyst torch tint. |

## Usage

```tsx
import Torchlight from "@/components/registry/torchlight/torchlight";

<Torchlight
  radius={140}
  softness={0.5}
  darkness={0.92}
  restReveal={0}
  smoothing={0.15}
  flicker={0.15}
  torchColor="#a855f7"
/>
```

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`.
- 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.
- `lib/utils.ts` is required, not optional. It exports the `cn` helper the component imports from `@/lib/utils` — keep it at that path, or rewrite every `cn` import to wherever you already keep yours. If your project is shadcn-based you almost certainly have this file already; keep yours and drop mine.

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