# Integrate `Tear` from Motion Garden

You are helping me add the **Tear** 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:** Tear
- **Category:** Micro-interactions
- **Summary:** A ticket with a perforated stub you tear off for real. The ticket is drawn twice and cut from one seeded jag polygon: an attached layer holds everything still connected, the body plus the stub below the tear front, and a flap layer holds only the freed part, rotated about the frontmost attached point, so the torn edges mate tooth for tooth and the swing can never overlap the body. The seam fights back through a resistance curve, a failed tear springs shut, and a completed one lets the stub fall under gravity carrying the release velocity. The jag array comes from a seeded PRNG so the edge never boils between renders.
- **Reference:** https://motion-garden.netlify.app/components/tear
- **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
# Tear needs no npm packages
```

## Design tokens this source uses

Some classes in the source are Motion Garden theme tokens, not stock Tailwind (`text-ink`, `bg-panel`, `font-display` and the like). Without them, parts of the component render unstyled. Add this to my global CSS, after the Tailwind import:

```css
@theme {
  --color-amethyst: #a855f7;
  --font-display: "Space Mono", ui-monospace, "SFMono-Regular", monospace;
}
```

The values are Motion Garden's own light and dark themes. If my project already has tokens for these roles, point the `--sg-*` variables at mine instead and tell me which you mapped. `.dark` assumes class-based dark mode — adapt the selector to how my project switches themes.

`font-display` expects Space Mono, and this CSS only names it. Load the font (with `next/font/google`, for example) or put my own display face first in the stack; until then it falls back to the system monospace.

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

```tsx
"use client";

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

export interface TearProps {
  perforationAt?: number;
  jag?: number;
  teeth?: number;
  resistance?: number;
  gravity?: number;
  autoReset?: boolean;
  resetDelay?: number;
  inkColor?: string;
  onTear?: () => void;
  reducedMotion?: boolean;
  className?: string;
}

type Phase = "idle" | "dragging" | "springback" | "autotear" | "falling" | "gone";

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

const buildJag = (teeth: number, jag: number): number[] => {
  const rand = mulberry32(7);
  const offsets: number[] = [0];
  for (let i = 1; i < teeth; i++) offsets.push((rand() - 0.5) * 2 * jag * 6);
  offsets.push(0);
  return offsets;
};

const TicketFace = ({ ink, at }: { ink: string; at: number }) => (
  <div className="absolute inset-0 overflow-hidden rounded-lg">
    <div
      className="absolute inset-y-0 left-0 flex flex-col justify-between p-4"
      style={{ width: `${at * 100}%` }}
    >
      <div>
        <p
          className="font-display text-lg leading-none font-bold tracking-[0.08em]"
          style={{ color: ink }}
        >
          ADMIT ONE
        </p>
        <p className="mt-1.5 font-mono text-[9px] tracking-[0.24em] text-[#8b87a0] uppercase">
          Motion Garden · Hall C
        </p>
      </div>
      <p className="font-mono text-[10px] tracking-[0.18em] text-[#6e6a82]">
        ROW 07 · SEAT 21
      </p>
    </div>
    <div
      className="absolute inset-y-0 border-l-2 border-dashed"
      style={{
        left: `${at * 100}%`,
        borderColor: `color-mix(in oklab, ${ink} 40%, transparent)`,
      }}
    />
    <div
      className="absolute inset-y-0 flex flex-col items-center justify-between py-4"
      style={{ left: `${at * 100}%`, right: 0 }}
    >
      <p className="font-mono text-[9px] tracking-[0.2em] text-[#8b87a0]">No. 0921</p>
      <div className="flex h-10 items-stretch gap-[3px] px-3">
        {[3, 1, 2, 1, 3, 2, 1, 1, 2, 3, 1, 2].map((w, i) => (
          <div key={i} style={{ width: w, background: ink, opacity: 0.85 }} />
        ))}
      </div>
      <p className="font-mono text-[9px] tracking-[0.3em] text-[#6e6a82]">STUB</p>
    </div>
  </div>
);

const Tear = ({
  perforationAt = 0.62,
  jag = 0.6,
  teeth = 26,
  resistance = 0.6,
  gravity = 1,
  autoReset = true,
  resetDelay = 1800,
  inkColor = "#c4b5fd",
  onTear,
  reducedMotion = false,
  className = "",
}: TearProps) => {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const ticketRef = useRef<HTMLDivElement | null>(null);
  const attachedRef = useRef<HTMLDivElement | null>(null);
  const flapRef = useRef<HTMLDivElement | null>(null);

  const jagOffsets = useMemo(() => buildJag(Math.round(teeth), jag), [teeth, jag]);

  const live = useRef({
    perforationAt,
    resistance,
    gravity,
    autoReset,
    resetDelay,
    reducedMotion,
    jagOffsets,
    onTear,
  });
  live.current = {
    perforationAt,
    resistance,
    gravity,
    autoReset,
    resetDelay,
    reducedMotion,
    jagOffsets,
    onTear,
  };

  const sim = useRef({
    phase: "idle" as Phase,
    w: 0,
    h: 0,
    front: 0,
    frontV: 0,
    drive: 0,
    startX: 0,
    startY: 0,
    samples: [] as Array<{ t: number; x: number; y: number }>,
    px: 0,
    py: 0,
    vx: 0,
    vy: 0,
    rot: 0,
    rotV: 0,
    fallT: 0,
    healLeft: 0,
    lastAttached: "",
    lastFlap: "",
  });

  const seamX = (f: number) => {
    const s = sim.current;
    const offs = live.current.jagOffsets;
    const seam = s.w * live.current.perforationAt;
    const scaled = f * (offs.length - 1);
    const i = Math.min(offs.length - 2, Math.floor(scaled));
    const frac = scaled - i;
    return seam + offs[i] + (offs[i + 1] - offs[i]) * frac;
  };

  const applyClips = () => {
    const s = sim.current;
    const attached = attachedRef.current;
    const flap = flapRef.current;
    if (!attached || !flap || s.w <= 0) return;
    const offs = live.current.jagOffsets;
    const n = offs.length - 1;
    const f = Math.min(Math.max(s.front, 0), 1);
    const frontY = f * s.h;

    const a: string[] = [`0px 0px`, `${seamX(0).toFixed(1)}px 0px`];
    const kMax = Math.floor(f * n);
    for (let k = 1; k <= kMax; k++) {
      a.push(`${(s.w * live.current.perforationAt + offs[k]).toFixed(1)}px ${((k / n) * s.h).toFixed(1)}px`);
    }
    a.push(`${seamX(f).toFixed(1)}px ${frontY.toFixed(1)}px`);
    a.push(`${s.w}px ${frontY.toFixed(1)}px`);
    a.push(`${s.w}px ${s.h}px`, `0px ${s.h}px`);
    const aClip = `polygon(${a.join(", ")})`;
    if (aClip !== s.lastAttached) {
      attached.style.clipPath = aClip;
      s.lastAttached = aClip;
    }

    if (f <= 0.001 && s.phase !== "falling" && s.phase !== "gone") {
      if (s.lastFlap !== "hidden") {
        flap.style.opacity = "0";
        s.lastFlap = "hidden";
      }
      return;
    }
    const b: string[] = [`${seamX(0).toFixed(1)}px 0px`, `${s.w}px 0px`];
    b.push(`${s.w}px ${frontY.toFixed(1)}px`);
    b.push(`${seamX(f).toFixed(1)}px ${frontY.toFixed(1)}px`);
    for (let k = kMax; k >= 1; k--) {
      b.push(`${(s.w * live.current.perforationAt + offs[k]).toFixed(1)}px ${((k / n) * s.h).toFixed(1)}px`);
    }
    const bClip = `polygon(${b.join(", ")})`;
    if (bClip !== s.lastFlap) {
      flap.style.clipPath = bClip;
      flap.style.opacity = "1";
      s.lastFlap = bClip;
    }
  };

  const applyFlapTransform = (opacity = 1) => {
    const s = sim.current;
    const flap = flapRef.current;
    if (!flap) return;
    const f = Math.min(Math.max(s.front, 0), 1);
    const originX = seamX(f);
    const originY = f * s.h;
    flap.style.transformOrigin = `${originX}px ${originY}px`;
    if (s.phase === "falling" || s.phase === "gone") {
      flap.style.transform = `translate3d(${s.px.toFixed(1)}px, ${s.py.toFixed(1)}px, 0) rotate(${s.rot.toFixed(2)}deg)`;
      flap.style.opacity = String(Math.max(opacity, 0));
    } else {
      const swing = f * 13;
      flap.style.transform = `translate3d(${(f * 5).toFixed(1)}px, 0px, 0) rotate(${swing.toFixed(2)}deg)`;
    }
  };

  const measureRef = useRef<((m: Metrics) => void) | null>(null);

  const loop = useAnimationLoop({
    target: containerRef,
    halted: false,
    onResize: (m) => measureRef.current?.(m),
    onFrame: ({ dt }) => {
      const s = sim.current;
      const cfg = live.current;
      if (s.w <= 0) return false;

      if (s.phase === "idle") {
        applyClips();
        return false;
      }

      if (s.phase === "dragging") {
        applyClips();
        applyFlapTransform();
        return;
      }

      if (s.phase === "springback") {
        if (cfg.reducedMotion) {
          s.front = 0;
          s.frontV = 0;
        } else {
          s.frontV += (-260 * s.front - 22 * s.frontV) * dt;
          s.front += s.frontV * dt;
        }
        if (s.front <= 0.002 && Math.abs(s.frontV) < 0.02) {
          s.front = 0;
          s.frontV = 0;
          s.phase = "idle";
        }
        applyClips();
        applyFlapTransform();
        return;
      }

      if (s.phase === "autotear") {
        s.front = Math.min(1, s.front + dt * 1.6);
        applyClips();
        applyFlapTransform();
        if (s.front >= 1) release(0, 120);
        return;
      }

      if (s.phase === "falling") {
        s.fallT += dt;
        s.vy += 1400 * cfg.gravity * dt;
        s.px += s.vx * dt;
        s.py += s.vy * dt;
        s.rot += s.rotV * dt;
        const fade = Math.min(Math.max((s.fallT - 0.3) / 0.45, 0), 1);
        applyFlapTransform(1 - fade);
        if (fade >= 1 || s.py > s.h * 3) {
          s.phase = "gone";
          s.healLeft = cfg.resetDelay / 1000;
        }
        return;
      }

      if (!cfg.autoReset) return false;
      s.healLeft -= dt;
      if (s.healLeft <= 0) {
        s.front = 0;
        s.frontV = 0;
        s.px = 0;
        s.py = 0;
        s.rot = 0;
        s.fallT = 0;
        s.phase = "idle";
        const flap = flapRef.current;
        if (flap) {
          flap.style.transform = "";
          flap.style.opacity = "0";
          s.lastFlap = "hidden";
        }
        applyClips();
        return false;
      }
    },
  });

  const release = (vx: number, vy: number) => {
    const s = sim.current;
    const cfg = live.current;
    s.phase = "falling";
    s.fallT = 0;
    s.px = 0;
    s.py = 0;
    s.vx = vx * 0.5;
    s.vy = Math.max(vy * 0.5, 60);
    s.rotV = vx * 0.12 + 40;
    cfg.onTear?.();
    if (cfg.reducedMotion) {
      s.phase = "gone";
      s.healLeft = cfg.resetDelay / 1000;
      const flap = flapRef.current;
      if (flap) {
        flap.style.opacity = "0";
        s.lastFlap = "hidden";
      }
    }
  };

  const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
    const s = sim.current;
    if (s.phase === "falling" || s.phase === "gone" || s.phase === "autotear") return;
    e.currentTarget.setPointerCapture(e.pointerId);
    s.phase = "dragging";
    s.startX = e.clientX;
    s.startY = e.clientY;
    s.samples = [{ t: e.timeStamp, x: e.clientX, y: e.clientY }];
    loop.start();
  };

  const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
    const s = sim.current;
    const cfg = live.current;
    if (s.phase !== "dragging") return;
    const dx = e.clientX - s.startX;
    const dy = e.clientY - s.startY;
    s.drive = Math.max(0, dy + Math.max(dx, 0) * 0.5);
    const u = Math.min(s.drive / (s.h * 1.15), 1);
    s.front = Math.pow(u, 1 + cfg.resistance * 1.6);
    if (cfg.reducedMotion && u >= 0.35) {
      s.front = 1;
      release(0, 80);
      return;
    }
    if (s.front >= 1) {
      const first = s.samples[0];
      const lastS = s.samples[s.samples.length - 1];
      const span = lastS && first ? lastS.t - first.t : 0;
      release(
        span > 8 ? ((lastS.x - first.x) / span) * 1000 : 0,
        span > 8 ? ((lastS.y - first.y) / span) * 1000 : 0,
      );
      return;
    }
    s.samples.push({ t: e.timeStamp, x: e.clientX, y: e.clientY });
    if (s.samples.length > 4) s.samples.shift();
    loop.start();
  };

  const onPointerUp = () => {
    const s = sim.current;
    if (s.phase !== "dragging") return;
    s.phase = s.front > 0 ? "springback" : "idle";
    s.drive = 0;
    loop.start();
  };

  const onKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
    const s = sim.current;
    if (e.key !== "Enter" && e.key !== " ") return;
    e.preventDefault();
    if (s.phase !== "idle") return;
    if (live.current.reducedMotion) {
      s.front = 1;
      release(0, 80);
    } else {
      s.phase = "autotear";
    }
    loop.start();
  };

  useEffect(() => {
    measureRef.current = () => {
      const ticket = ticketRef.current;
      if (!ticket) return;
      const rect = ticket.getBoundingClientRect();
      if (rect.width <= 0 || rect.height <= 0) return;
      const s = sim.current;
      s.w = rect.width;
      s.h = rect.height;
      s.lastAttached = "";
      s.lastFlap = "";
      applyClips();
      applyFlapTransform();
    };
    loop.resize();
    return () => {
      measureRef.current = null;
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [loop]);

  useEffect(() => {
    const s = sim.current;
    s.lastAttached = "";
    s.lastFlap = "";
    loop.paint();
  }, [jagOffsets, perforationAt, loop]);

  useEffect(() => {
    loop.start();
  }, [autoReset, loop]);

  return (
    <div
      ref={containerRef}
      className={`flex h-full w-full touch-none items-center justify-center select-none ${className}`.trim()}
    >
      <div ref={ticketRef} className="relative aspect-[2.15/1] w-[min(86%,360px)]">
        <div
          ref={attachedRef}
          className="absolute inset-0 rounded-lg border border-[#33333e] bg-[#17151d] shadow-[0_10px_30px_rgba(0,0,0,0.4)]"
        >
          <TicketFace ink={inkColor} at={perforationAt} />
        </div>
        <div
          ref={flapRef}
          aria-hidden="true"
          className="pointer-events-none absolute inset-0 rounded-lg border border-[#33333e] bg-[#17151d] opacity-0 will-change-transform"
        >
          <TicketFace ink={inkColor} at={perforationAt} />
        </div>
        <div
          role="button"
          tabIndex={0}
          aria-label="Tear off the ticket stub"
          className="absolute inset-y-0 right-0 cursor-grab rounded-r-lg outline-none focus-visible:ring-2 focus-visible:ring-amethyst active:cursor-grabbing"
          style={{ left: `${perforationAt * 100}%` }}
          onPointerDown={onPointerDown}
          onPointerMove={onPointerMove}
          onPointerUp={onPointerUp}
          onPointerCancel={onPointerUp}
          onKeyDown={onKeyDown}
        />
      </div>
    </div>
  );
};

export default Tear;
```

### 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 |
| --- | --- | --- | --- |
| `perforationAt` | `number` | `0.62` | Where the seam sits across the ticket. Range 0.35–0.8. |
| `jag` | `number` | `0.6` | Roughness of the torn edge — 0 is a die-cut, 1 is a bad day. Range 0–1. |
| `teeth` | `number` | `26` | Perforation tooth count; also the resolution of the torn edge. Range 10–48. |
| `resistance` | `number` | `0.6` | How hard the seam fights before it lets go. Range 0.1–1. |
| `gravity` | `number` | `1` | How fast the freed stub falls away. Range 0–3 ×. |
| `autoReset` | `boolean` | `true` | Heal the ticket after the stub is gone. |
| `resetDelay` | `number` | `1800` | Dwell before the ticket heals. Range 500–5000 ms. Ignored while `autoReset` is `false`. |
| `inkColor` | `string (hex)` | `"#c4b5fd"` | The ticket's printed ink — title, seat block, barcode. |

## Usage

```tsx
import Tear from "@/components/registry/tear/tear";

<Tear
  perforationAt={0.62}
  jag={0.6}
  teeth={26}
  resistance={0.6}
  gravity={1}
  autoReset={true}
  resetDelay={1800}
  inkColor="#c4b5fd"
/>
```

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.
- 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. Add the design tokens to my global CSS, or map them to tokens I already have.
4. Wire the component into the place I point you at, with sensible props for that context.
5. 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.
